MCP Endpoint Handler

[cstns]

Summary

Implement the stateless Streamable HTTP endpoint handler at POST /api/v1/mcp. This fills in the empty route shell from #7426 with the per-request McpServer lifecycle, authentication enforcement, and the Fastify-to-MCP transport bridge. Tool definitions are not part of this task; the endpoint ships with an empty tool list and a registration hook for subsequent tasks to plug into.

Prerequisites

• Scaffolding: Dependencies, Feature Flag, and Route Shell #7426 (scaffolding: dependencies, feature flag, route reorganization, route shell)
• Add PAT (Personal Acces Tokens) scopes #7411 (PAT scopes) is assumed to be implemented. PAT scope enforcement on individual tool calls is handled in the tool definitions task, not here.

Requirements

Endpoint handler

• POST /api/v1/mcp: each request creates a fresh McpServer and StreamableHTTPServerTransport (stateless, sessionIdGenerator: undefined)
• Call reply.hijack() then delegate to transport.handleRequest(request.raw, reply.raw, request.body). The third parsedBody argument is a supported SDK parameter for frameworks that pre-parse the request body.
• After handling, call mcpServer.close() and transport.close() to clean up per-request resources
• GET /api/v1/mcp and DELETE /api/v1/mcp return 405 (not applicable for stateless mode)

Authentication

• verifySession (inherited from the parent EE routes hook) handles PAT resolution from the Authorization header, no additional auth wiring needed
• Add a preHandler that rejects requests without a resolved request.session.User (e.g. project/device tokens, missing auth) with 401
• Reject requests where the PAT has adminOptIn enabled with 403. Admin users can use MCP with tokens that have admin opt-in disabled (the token behaves as a regular user scoped to their team role). See Add PAT (Personal Acces Tokens) scopes #7411 for the admin opt-in model.
• Errors return structured JSON with code and error fields, descriptive enough for an LLM agent to relay to the user

Tool registration hook

• Expose a mechanism for tool definition modules to register themselves on the per-request McpServer
• Tool modules export entries of { name, description, inputSchema, annotations, handler }, endpoint iterates and calls mcpServer.registerTool() for each
• Ships with zero tools: tools/list returns empty array, tools/call rejects unknown tools

Tests

• POST /api/v1/mcp with valid PAT returns a valid MCP JSON-RPC response (tools/list returns empty array)
• POST /api/v1/mcp without auth returns 401
• POST /api/v1/mcp with a PAT that has adminOptIn = true returns 403
• POST /api/v1/mcp with a PAT owned by an admin but with adminOptIn = false succeeds (token behaves as regular user)
• GET /api/v1/mcp returns 405
• DELETE /api/v1/mcp returns 405
• Stateless behavior: no session state leaks between sequential requests

References

• MCP SDK: McpServer from @modelcontextprotocol/sdk/server/mcp.js, StreamableHTTPServerTransport from @modelcontextprotocol/sdk/server/streamableHttp.js
• verifySession: forge/routes/auth/index.js:65-165
• POC reference: PR feat: MCP platform server (proof of concept) #7414, forge/ee/routes/mcpServer/index.js (reference only, not to be reused as-is)
• Parent story: Story 1: MCP Platform Tools Server #7422