MCP — connect your AI

Connect Cursor, Claude Desktop, Claude Code, Codex, OpenCode, and ChatGPT to orkai via the Model Context Protocol.

orkai exposes a local MCP server so your AI assistant can search indexed knowledge, store sessions, read standards, index code, and run review — without copying context into chat by hand. The CLI command orkai mcp-config detects installed clients and can print a paste block or add/update orkai in each client's tool config file.

orkai mcp-config

Run this in your terminal. It resolves your local SSE URL and bearer token. On a TTY with no flags it detects installed clients, lets you multi-select, then asks Print versus Add / update in the tool config file. --print and --client still emit paste blocks. orkai mcp-config --apply --client cursor writes without a menu.

orkai mcp-config                          # TTY: detect, then print or add/update
orkai mcp-config --print                 # detect + print paste blocks
orkai mcp-config --client cursor         # Cursor paste block
orkai mcp-config --client windsurf       # Windsurf paste block
orkai mcp-config --client cline          # Cline (VS Code / CLI)
orkai mcp-config --client claude-desktop # Claude Desktop (mcp-remote)
orkai mcp-config --client claude-code    # Claude Code
orkai mcp-config --client codex          # OpenAI Codex CLI
orkai mcp-config --client opencode       # OpenCode
orkai mcp-config --client chatgpt        # ChatGPT Developer Mode
orkai mcp-config --apply --client cursor # write ~/.cursor/mcp.json

Print output goes to stdout. Merge a paste block into the existing file (do not replace other MCP servers). Add / update writes only the orkai entry.

How orkai speaks MCP

orkai implements the classic HTTP + SSE transport: your client opens an event stream at GET /sse and sends JSON-RPC at POST /message. Authentication is a bearer token in the Authorization header.

Not the same as Streamable HTTP. Some clients (notably Claude Code) also support a newer type: http transport on a single /mcp endpoint. orkai uses SSE today — use --transport sse in Claude Code, or the mcp-remote bridge if SSE misbehaves.

Client overview

Cursor

1. Run orkai mcp-config --client cursor.
2. Open Settings → MCP or edit ~/.cursor/mcp.json. Merge the mcpServers.orkai entry — keep your other servers.
3. Restart Cursor if tools do not appear. MCP tools work in Agent mode.

Shape (values filled in by the CLI):

{
  "mcpServers": {
    "orkai": {
      "url": "http://127.0.0.1:8787/sse",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Windsurf

Windsurf Cascade uses its own dest and object. Run orkai mcp-config --client windsurf and merge into ~/.codeium/windsurf/mcp_config.json. The remote field is serverUrl, not Cursor's url.

Shape (values filled in by the CLI):

{
  "mcpServers": {
    "orkai": {
      "serverUrl": "http://127.0.0.1:8787/sse",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Cline

Cline is a VS Code extension (and CLI) that supports remote SSE servers natively. Run orkai mcp-config --client cline and merge the output into ~/.cline/mcp.json, or use the Cline panel: MCP Servers → Configure → Configure MCP Servers to open the settings JSON.

Shape (values filled in by the CLI):

{
  "mcpServers": {
    "orkai": {
      "url": "http://127.0.0.1:8787/sse",
      "headers": {
        "Authorization": "Bearer <token>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Claude Desktop

Claude Desktop does not accept a bare url + headers block. It only starts local stdio processes. orkai's output wraps the SSE endpoint with mcp-remote (requires Node.js and npx).

1. Run orkai mcp-config --client claude-desktop.
2. Paste into claude_desktop_config.json under mcpServers (macOS: ~/Library/Application Support/Claude/).
3. Quit Claude Desktop completely and reopen.

Shape:

{
  "mcpServers": {
    "orkai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8787/sse",
        "--allow-http",
        "--transport",
        "sse-only",
        "--header",
        "Authorization:${ORKAI_AUTH}"
      ],
      "env": {
        "ORKAI_AUTH": "Bearer <token>"
      }
    }
  }
}

Claude Code

Claude Code supports remote SSE. Prefer the CLI printed by orkai mcp-config --client claude-code (or --apply --client claude-code). File fallback is user-scope ~/.claude.json with required type: sse.

Option A — CLI (recommended)

claude mcp add orkai "http://127.0.0.1:8787/sse" -t sse -s user -H "Authorization: Bearer <token>"

Option B — ~/.claude.json (when claude is not on PATH)

{
  "mcpServers": {
    "orkai": {
      "type": "sse",
      "url": "http://127.0.0.1:8787/sse",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

OpenAI Codex

Codex reads MCP servers from ~/.codex/config.toml. orkai mcp-config --apply --client codex writes an mcp-remote stdio block with the bearer token in the file (not bearer_token_env_var alone).

# ~/.codex/config.toml
[mcp_servers.orkai]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:8787/sse", "--allow-http", "--transport", "sse-only", "--header", "Authorization:${ORKAI_AUTH}"]
startup_timeout_sec = 60

[mcp_servers.orkai.env]
ORKAI_AUTH = "Bearer <token>"

OpenCode

OpenCode uses a top-level mcp key (not mcpServers). Run orkai mcp-config --client opencode and merge into ~/.config/opencode/opencode.json.

{
  "mcp": {
    "orkai": {
      "type": "remote",
      "url": "http://127.0.0.1:8787/sse",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

ChatGPT (Developer Mode)

Cloud ChatGPT cannot reach 127.0.0.1. For local orkai you need a tunnel (ngrok, Cloudflare Tunnel) or remote mode with a reachable host. Run orkai mcp-config --client chatgpt for paste instructions:

• Settings → Apps → Advanced → Developer mode → Create app
• Connector URL: your public HTTPS SSE URL (or tunneled local URL)
• Custom header: Authorization: Bearer <token>

Custom MCP on Plus/Pro is read-only; write tools need Business, Enterprise, or Edu plans.

Verify the connection

1. In your assistant, start a new session (or reload MCP).
2. Ask the agent to call overview() — you should see recent sessions, standards, and tool names scoped to orkai.
3. If tools are missing: confirm orkai status, re-run orkai mcp-config (token/port may have changed), and fully restart the client.

Troubleshooting

Daemon commands (start, stop, status, ports, logs) are documented on Daemon & MCP. MCP port and auth keys live in Configuration.