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 memory, store sessions, read standards, index code, and run review — without copying context into chat by hand. The CLI command orkai mcp-config prints a ready-to-paste block for each supported client.

orkai mcp-config

Run this in your terminal. It resolves your local SSE URL and bearer token, then prints config for every supported client (default). Use --client when you only want one block.

orkai mcp-config                          # all clients (default)
orkai mcp-config --client cursor         # Cursor / Windsurf / Cline
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

Output goes to stdout — copy the section for your client and merge it into the existing config file (do not replace other MCP servers).

How orkai speaks MCP

orkai implements the classic HTTP + SSE transport: your client opens an event stream at GET /v2/sse and sends JSON-RPC at POST /v2/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/v2/sse",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Windsurf & Cline

Use the same JSON as Cursor (orkai mcp-config --client cursor). Windsurf typically reads ~/.windsurf/mcp_config.json. Cline follows the VS Code / Cursor-style MCP panel in your editor.

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/v2/sse",
        "--header",
        "Authorization:${ORKAI_AUTH}"
      ],
      "env": {
        "ORKAI_AUTH": "Bearer <token>"
      }
    }
  }
}

Claude Code

Claude Code supports remote SSE (deprecated but still works for servers like orkai). Prefer the CLI hint printed by orkai mcp-config --client claude-code — headers are forwarded reliably on tool calls.

Option A — CLI (recommended)

claude mcp add orkai "http://127.0.0.1:8787/v2/sse" \
  --transport sse -s user \
  --header "Authorization: Bearer <token>"

Option B — project .mcp.json

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

Fallback: if SSE fails, use the Claude Desktop block (mcp-remote) in .mcp.json instead — same stdio bridge pattern.

OpenAI Codex

Codex reads MCP servers from ~/.codex/config.toml. The CLI prints a TOML snippet plus a one-liner to register via codex mcp add.

# ~/.codex/config.toml
[mcp_servers.orkai]
url = "http://127.0.0.1:8787/v2/sse"
bearer_token_env_var = "ORKAI_MCP_TOKEN"
enabled = true

# In your shell:
export ORKAI_MCP_TOKEN="<token>"

OpenCode

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

{
  "mcp": {
    "orkai": {
      "type": "remote",
      "url": "http://127.0.0.1:8787/v2/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.