OpenSEO's MCP transport routes requests by type—preflight CORS, legacy JSON-RPC, or modern MCP—with separate handlers for hosted (OAuth-authenticated) and self-hosted deployments; hosted requests enforce strict origin validation plus OAuth scope gates, while self-hosted requests rely on local identity resolution. The OAuth provider issues MCP access tokens (24-hour TTL) and refresh tokens (30-day TTL), grants all configured scopes by default, protects the consent endpoint against CSRF, and logs authorization to PostHog after successful consent.
createRequestHandler in src/server/mcp/transport.ts routes OPTIONS preflight requests to an immediate CORS-headers response, returns 404 for paths other than MCP_ROUTE, delegates modern requests to the agents SDK handler, and falls through to handleLegacyJsonRequest for detected legacy requests. The modern MCP handler in src/server/mcp/transport.ts is created with legacy: "reject", so createMcpHandler from the agents SDK never falls back to legacy behaviour — legacy requests are handled entirely by handleLegacyJsonRequest in the same file. handleLegacyJsonRequest in src/server/mcp/transport.ts rejects non-POST methods with a JSON-RPC 2.0 error (code: -32000, status: 405) before processing legacy MCP requests.
The MCP CORS headers in src/server/mcp/transport.ts mirror the agents SDK's DEFAULT_CORS_OPTIONS, including Access-Control-Allow-Origin: *, Access-Control-Max-Age: 86400, and the exposed header mcp-session-id. The Surfmind Chrome extension (chrome-extension://pghallcbnfabbgfijhbcldaapmgidnaa) is explicitly allowlisted as an accepted origin for hosted MCP requests in src/server/mcp/transport.ts.
Hosted MCP requests in src/server/mcp/transport.ts enforce exact-origin validation against the hosted base URL and the Surfmind Chrome extension origin; any other Origin header returns 403. Self-hosted requests leave allowedOriginHostnames unset, relying on the SDK's localhost-class default — an explicit per-request Host-derived allowlist is deliberately avoided to prevent DNS-rebinding attacks. validateLegacyRequest in src/server/mcp/transport.ts applies host-header validation only for localhost and .workers.dev hostnames; for other hosts (production deployments), host validation is skipped and only origin validation is applied against the caller-supplied allowedOriginHostnames.
handleAuthenticatedOpenSeoMcpRequest in src/server/mcp/transport.ts enforces two hard gates before serving: the props must parse against hostedWorkersOAuthMcpPropsSchema (403 if not), and the auth context must include MCP_SCOPE (403 if missing). Only then does it proceed to host/origin validation. handleSelfHostedOpenSeoMcpRequest in src/server/mcp/transport.ts resolves identity via resolveLocalNoAuthContext for local_noauth mode or resolveCloudflareAccessContext for cloudflare_access mode, then calls createRequestHandler without an origin allowlist. The mcpApiHandler in src/server/mcp/oauth-provider.ts calls handleAuthenticatedOpenSeoMcpRequest with ctx.props as the OAuth props — the props originate from the Cloudflare Workers OAuth provider's execution context, not from the request body.
The OAuth provider in src/server/mcp/oauth-provider.ts sets MCP access token TTL to 24 hours (60 * 60 * 24 seconds) and refresh token TTL to 30 days (60 * 60 * 24 * 30 seconds). DCR (Dynamic Client Registration) records in src/server/mcp/oauth-provider.ts expire after 1 year (60 * 60 * 24 * 365 seconds); the rationale is that 30-day rolling refresh tokens already reap inactive clients' sessions, so a 1-year client registration TTL keeps the invalid_client cliff rare for actively-used clients. DCR (Dynamic Client Registration) is the OAuth mechanism by which an MCP client automatically registers itself with the provider at runtime; without a valid DCR record, the provider rejects the client with an invalid_client error.
getGrantedMcpScopes in src/server/mcp/oauth-provider.ts grants all MCP_OAUTH_SCOPES when the client requests no specific scopes, and throws if the filtered result does not include MCP_SCOPE (the mcp scope is required in all grants). The consent endpoint (/api/oauth/consent) in src/server/mcp/oauth-provider.ts is CSRF-protected: it checks that the Origin header matches the public origin of the request, returning 403 for mismatches. The OAuth authorize flow in src/server/mcp/oauth-provider.ts redirects unauthenticated users to /sign-in?redirect=<original-path> rather than returning an error, and returns 500 for missing Better Auth hosted configuration. After a successful OAuth consent, handleOAuthConsentResponse in src/server/mcp/oauth-provider.ts calls recordMcpAuthorized and fires a mcp:authorize_success PostHog event (via waitUntil) with client_id and scopes properties before returning the redirect URL.