MCP Gateway

​

1. Where it lives

​

2. Authentication — three credentials, one endpoint

​

2.1 OAuth 2.1 flow (spec-compliant MCP clients)

1. Client POSTs /oauth/register → {client_id, …}.
2. Client opens browser at /oauth/authorize?client_id=…&code_challenge=…&redirect_uri=…&state=….
3. MCP Gateway redirects to BeeOS web login (MCP_WEB_LOGIN_URL/mcp-login?return_to=…).
4. User signs into BeeOS, picks which agents to grant.
5. Web app redirects back to MCP Gateway, gateway redirects to redirect_uri with ?code=…&state=….
6. Client POSTs /oauth/token with code_verifier → access token.
7. Client uses token on /{agentId}/mcp from then on.

• Your BeeOS user account has at least one MCP-enabled agent (mcp_enabled=true). Check with GET /api/v1/agents on the OpenAPI surface — the mcp_enabled field surfaces in the catalog response.
• Your client’s redirect_uri is reachable from a browser (the authorization-code redirect can’t go to a non-routable host).
• For local dev: MCP_PUBLIC_URL=http://localhost:8094 is in the gateway’s env, and the web app at localhost:3000 exposes a /mcp-login route.

​

2.2 API-key-only flow (n8n, scripts, CI)

# n8n / CI: list this user's MCP-enabled agents
curl -X POST https://mcp.beeos.ai/<agentId>/mcp \
  -H "Authorization: Bearer oag_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Third-party app bound to ONE agent
curl -X POST https://mcp.beeos.ai/<agentId>/mcp \
  -H "X-Agent-API-Key: bak_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

• The key is bound to ONE agent — losing the key compromises only that integration, not your whole user account.
• It can be revoked independently of your oag_ keys.
• The agent owner (you) explicitly issued it, so consent is audit-traceable.

​

3. What each MCP method does

​

3.1 initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "clientInfo": { "name": "claude-desktop", "version": "0.7.0" }
  }
}

​

3.2 tools/list

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "agent_abc123",
        "description": "Analyze CSV files and produce a chart.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "message": { "type": "string" },
            "context_id": { "type": "string" }
          },
          "required": ["message"]
        }
      }
    ]
  }
}

​

3.3 tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "agent_abc123",
    "arguments": {
      "message": "What's the top-selling SKU last week?",
      "context_id": "ctx-uuid-optional"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "Top SKU last week: BLUE-42 (1,329 units)" }
    ]
  }
}

​

3.4 tools/call cancel

​

4. Behavioural contract — what MCP guarantees, what it doesn’t

• tools/list is read-only and idempotent. Safe to call repeatedly across reconnects.
• tools/call always delivers exactly one result (or one error) per JSON-RPC ID. Cancellation triggered server-side (deadline, agent crash) surfaces as a JSON-RPC error with a stable code from Error Reference.
• The same agent reachable via OpenAPI / A2A is reachable here; responses are bit-identical (same agent_reply from the same Message Service channel).
• Idempotency: pass params.arguments.idempotency_key and the gateway honours it on the underlying L0 invoke. See Calling Agents § Idempotency.
• Attachments: pass params.arguments.attachments[] with file_id values from POST /api/v1/files/presign-upload. The agent sees a normal multi-part chat_message.

• Durable async — MCP tools/call is request-response. Long-running work that needs to survive client disconnects belongs on OpenAPI tasks. Reaching for “fire-and-forget MCP tool” is a sign the protocol’s wrong for the use case.
• Multi-turn within one call — every tools/call is a fresh turn. To chain related turns, the MCP host typically keeps the conversation context client-side and includes the relevant history in the next message. If you need server-side conversation continuity, use the OpenAPI conversations surface and reference the conversation ID from arguments.context_id on MCP calls.
• Webhook push — MCP has no notion of server-pushed events outside the in-flight call. For “tell me when this task finishes” semantics, use OpenAPI webhooks (P2-A — see the webhooks guide).
• Rate-limit visibility — the gateway enforces rate limits per credential × agent, but rate-limit metadata is returned in the standard MCP error shape (code, message). Inspect the code (rate_limited) to back off; the wire doesn’t carry Retry-After today.

​

5. Common failure modes

​

6. End-to-end example — Claude Desktop

{
  "mcpServers": {
    "beeos-csv-analyst": {
      "transport": "streamable-http",
      "url": "https://mcp.beeos.ai/agent_abc123/mcp"
    }
  }
}

​

7. See also

• Choosing a Protocol — when MCP is the right surface vs. OpenAPI / A2A.
• Authentication & API Keys — oag_ / bak_ / OAuth lifecycle, scopes, rotation.
• Error Reference — stable wire codes the MCP error envelope can return.
• Public Architecture Overview — how MCP relates to the other two caller surfaces.
• backend/services/mcp-gateway/README.md — service-side README (env vars, local dev, deployment).
• MCP Authorization Spec — the canonical OAuth / DCR / PKCE spec the gateway implements.