History

Every saved version of decisions/remote-mcp.md, newest first. Each row shows what changed compared to the version before it.

• v1currentCreatedby agent · 18d ago
  Initial content

  # Remote MCP via Streamable HTTP
  
  ## Problem
  
  The first MCP shape was stdio-only. Users installing Hive's MCP had to clone the repo, install pnpm + ~700 deps, build, then hardcode the path:
  
  ```json
  "hive": {
    "command": "node",
    "args": ["/absolute/path/to/hive/packages/mcp/dist/index.js"],
    "env": { "HIVE_API_URL": "...", "HIVE_API_KEY": "..." }
  }
  ```
  
  Unshippable for non-developer users.
  
  ## Alternatives
  
  1. **`npx -y @hive/mcp` distributable** — publish to npm, users run `npx -y @hive/mcp`. Solves the clone-and-build problem but each user still spawns their own subprocess; no shared rate limiting, no centralized auth flow, can't be listed in connector directories.
  2. **OAuth 2.1 + PKCE + Dynamic Client Registration** (the 2025-11 MCP spec hardening). Required if we ever want to be in Claude.ai's connector directory. Multi-week effort, needs an IdP dependency.
  3. **Streamable HTTP + Bearer auth (chosen)** — host a `POST /mcp` endpoint on the existing API. Reuse `hive_pk_…` keys for auth. ~80 lines of new code. Spec calls this out as the right pattern for internal/single-tenant servers.
  
  ## What we chose
  
  Mount `POST /mcp` on the Hono API (`packages/api/src/routes/mcp.ts`). Each request:
  
  1. Auth middleware verifies `Authorization: Bearer hive_pk_…` → user.
  2. Builds a fresh `McpServer` + `StreamableHTTPServerTransport({ sessionIdGenerator: undefined })` — stateless mode, no persistent session tracking.
  3. Wraps the SDK call in `withApiContext({ baseUrl, token, clientLabel })` (`packages/mcp/src/client.ts`) — AsyncLocalStorage propagates the user's token into the tool handlers' `api()` calls without changing any handler signatures.
  4. `fetch-to-node` bridges Hono's Web Request → Node IncomingMessage/ServerResponse for the SDK.
  
  `createMcpServer()` (`packages/mcp/src/server.ts`) is shared between this HTTP route and the stdio entrypoint, so tool registry and resource handlers are defined once.
  
  GET and DELETE on `/mcp` return 405 — only meaningful in stateful streaming mode, which we don't run.
  
  Resulting user config:
  
  ```json
  {
    "mcpServers": {
      "hive": {
        "url": "https://hiveapi-production-bf0f.up.railway.app/mcp",
        "headers": { "Authorization": "Bearer hive_pk_..." }
      }
    }
  }
  ```
  
  Three lines, no clone, no build, no path placeholder.
  
  ## Why
  
  - **Bearer keys already exist** on Hive — users get one from `/settings/keys`. Reusing them dodges OAuth without losing per-user scoping.
  - **Hono can mount it on the same Railway service.** No second deployment, no second domain.
  - **Stateless per-request transport** avoids a known SDK bug (#1994) where reused stateless transports return 500s after the first POST.
  - **Tool descriptions and schemas are unchanged** between stdio and HTTP — same `toolRegistry`, same `createMcpServer()` factory.
  
  ## What we'd revisit
  
  - **OAuth 2.1 + DCR** when we want to be listed in Claude.ai's connector directory. The route is structured so a second auth path (alongside Bearer) is additive, not a rewrite.
  - **CORS for `claude.ai`** — the route-level CORS allows any origin. Production should narrow to the known set of Claude clients once that surface stabilizes.
  - **Multi-tenant analytics** — `wiki_reads` records per-user MCP reads, but the `X-Hive-Client` label propagation through loopback is best-effort. Not all MCP-via-HTTP reads are correctly attributed.
  
  See also [[bugs/mcp-body-stream-locked]] for the one non-obvious bug that surfaced during integration.