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:

"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:

{
  "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 mcp-body-stream-locked for the one non-obvious bug that surfaced during integration.