:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { isInsufficientScopeChallenge, isRejectedTokenChallenge, withResourceMetadata } from '@/lib/auth-errors'
import { resolveEffectiveClientName } from '@/lib/client-detection'
import { MCP_DOCS_URL, getAuthorizationServerUrl } from '@/lib/constants'
import { isIdJagAccessToken } from '@/lib/id-jag'
import { RequestLogger, withLogging } from '@/lib/logging'
import { extractClientInfoFromBody } from '@/lib/mcp-client-info'
import { corsHeadersForOAuthMetadata, oauthMetadataPreflightResponse } from '@/lib/oauth-metadata-cors'
import { RequestProperties } from '@/lib/request-properties'
import { buildRedirectUrl, getPublicUrl, getRegionFromRequest, matchAuthServerRedirect } from '@/lib/routing'
import { extractBearerToken, hash, parseMcpMode, sanitizeHeaderValue } from '@/lib/utils'
import { getAdvertisedOAuthScopes } from '@/tools/toolDefinitions'
import { proxyToHono, resolveProxyRegion } from './proxy'
const handleRequest = async (
request: Request,
env: Env,
ctx: ExecutionContext<RequestProperties>,
log: RequestLogger
): Promise<Response> => {
const url = new URL(request.url)
log.extend({ route: url.pathname })
if (url.pathname === '/') {
return Response.redirect(MCP_DOCS_URL, 302)
}
// OpenAI ChatGPT App Directory domain verification
if (url.pathname === '/.well-known/openai-apps-challenge') {
return new Response('pRLV9JYbPOF5Dy039v3Rn3-qrMuKqZ2_4SsX9GoL9aU', {
headers: { 'content-type': 'text/plain' },
})
}
// Health endpoint for uptime probes and load-balancer checks.
// Public and unauthenticated so external monitors can hit it without a token.
if (url.pathname === '/health' || url.pathname === '/healthz') {
return new Response(JSON.stringify({ status: 'ok' }), {
headers: {
'Content-Type': 'application/json',
'Cache-Control': 'no-store',
},
})
}
// Static MCP UI app bundles (`/ui-apps/<app>/main.js`,
// `/ui-apps/<app>/styles.css`). Production's Cloudflare edge already
// routes these to the asset binding before the Worker runs, but
// `wrangler dev` invokes the Worker first — without this short-circuit,
// the OAuth gate below 401s the request before assets get a chance.
if (url.pathname.startsWith('/ui-apps/')) {
return env.ASSETS.fetch(request)
}
// Detect region from hostname (mcp-eu.posthog.com) or query param (?region=eu)
// Hostname takes precedence as it's the workaround for Claude Code's OAuth bug
const effectiveRegion = getRegionFromRequest(request)
log.extend({ region: effectiveRegion })
// Authorization server redirects
//
// MCP clients sometimes hit OAuth endpoints directly on this server instead of
// following URLs from the authorization server metadata. We redirect these to
// the correct PostHog authorization server for the user's region.
// See: https://github.com/anthropics/claude-code/issues/2267
const redirect = matchAuthServerRedirect(url.pathname)
if (redirect) {
const authServer = getAuthorizationServerUrl()
const redirectTo = buildRedirectUrl(authServer, url.pathname, url.search, redirect)
log.extend({ redirectTo })
return Response.redirect(redirectTo, redirect.status)
}
// The legacy SSE transport (`/sse`) is deprecated in favor of `/mcp`
// (Streamable HTTP). Permanently redirect `/sse*` to the equivalent `/mcp*`.
// We tag the redirect Location with `_deprecated=sse` so the followup
// request on /mcp carries the marker — that lets us correlate
// success/failure on /mcp back to clients that came in via the deprecated
// path, even after the protocol-level handoff.
if (url.pathname === '/sse' || url.pathname.startsWith('/sse/')) {
const target = getPublicUrl(request)
target.pathname = '/mcp' + url.pathname.slice('/sse'.length)
target.searchParams.set('_deprecated', 'sse')
log.extend({ deprecation: 'sse', redirectTo: target.toString() })
return Response.redirect(target.toString(), 308)
}
// OAuth Protected Resource Metadata (RFC 9728)
// This endpoint tells MCP clients where to authenticate to get tokens.
//
// Per RFC 9728, the well-known URL is constructed by inserting /.well-known/oauth-protected-resource
// between the host and the path. For example:
// - Resource: https://mcp.posthog.com/mcp → Well-known: https://mcp.posthog.com/.well-known/oauth-protected-resource/mcp
//
// OAuth flow for MCP:
// 1. Client connects to MCP server without a token
// 2. MCP returns 401 with WWW-Authenticate header pointing to this metadata endpoint
// 3. Client fetches this metadata to discover the authorization server
// 4. Client performs OAuth flow with PostHog (US or EU based on region param)
// 5. Client reconnects to MCP with the access token
const wellKnownPrefix = '/.well-known/oauth-protected-resource'
if (url.pathname.startsWith(wellKnownPrefix)) {
const preflight = oauthMetadataPreflightResponse(request)
if (preflight) {
return preflight
}
// Extract the resource path from after the well-known prefix
// e.g., /.well-known/oauth-protected-resource/mcp → /mcp
const resourcePath = url.pathname.slice(wellKnownPrefix.length) || '/'
const resourceUrl = getPublicUrl(request)
resourceUrl.pathname = resourcePath
resourceUrl.search = ''
// Determine authorization server for OAuth.
// POSTHOG_API_BASE_URL takes precedence for self-hosted, otherwise routes to oauth.posthog.com.
const authorizationServer = getAuthorizationServerUrl()
return new Response(
JSON.stringify({
resource: resourceUrl.toString().replace(/\/$/, ''),
authorization_servers: [authorizationServer],
scopes_supported: getAdvertisedOAuthScopes(),
bearer_methods_supported: ['header'],
}),
{
headers: {
'Content-Type': 'application/json',
'Cache-Control': 'public, max-age=3600',
...corsHeadersForOAuthMetadata(request),
},
}
)
}
const token = extractBearerToken(request)
const sessionId = url.searchParams.get('sessionId')
if (!token) {
// Return 401 with WWW-Authenticate header per RFC 9728.
// The resource_metadata URL tells OAuth-capable clients where to discover auth server.
// Per RFC 9728, the well-known URL is constructed by inserting the well-known path
// between the host and the resource path:
// - Resource /mcp → metadata at /.well-known/oauth-protected-resource/mcp
const metadataUrl = getPublicUrl(request)
metadataUrl.pathname = `/.well-known/oauth-protected-resource${url.pathname}`
metadataUrl.search = ''
if (effectiveRegion) {
metadataUrl.searchParams.set('region', effectiveRegion)
}
log.extend({ authError: 'no_token' })
return new Response(
`No token provided, please provide a valid API token. View the documentation for more information: ${MCP_DOCS_URL}`,
{
status: 401,
headers: { 'WWW-Authenticate': `Bearer resource_metadata="${metadataUrl.toString()}"` },
}
)
}
if (!token.startsWith('phx_') && !token.startsWith('pha_') && !isIdJagAccessToken(token)) {
log.extend({ authError: 'invalid_token_format' })
return new Response(
`Invalid token, please provide a valid API token. View the documentation for more information: ${MCP_DOCS_URL}`,
{ status: 401 }
)
}
// Organization and project IDs can be provided via headers or query params.
// When set, they pin the MCP session to a specific org/project and remove the switch tools.
const organizationId =
request.headers.get('x-posthog-organization-id') || url.searchParams.get('organization_id') || undefined
const projectId = request.headers.get('x-posthog-project-id') || url.searchParams.get('project_id') || undefined
const rawUserAgent = request.headers.get('User-Agent') || undefined
const clientUserAgent = sanitizeHeaderValue(rawUserAgent)
// Self-identification signal set by a wrapping consumer app (e.g. PostHog's
// Tasks sandbox, or an AI-tool plugin that auto-installs the MCP) when the
// wrapped MCP client's name is too generic to distinguish (e.g. both direct
// and sandboxed Claude Code send `claude-code`). Query-param fallback for
// clients that only let the user customize the URL, not headers.
const mcpConsumer = sanitizeHeaderValue(
request.headers.get('x-posthog-mcp-consumer') || url.searchParams.get('consumer') || undefined
)
// Extract MCP `clientInfo` eagerly from the JSON-RPC initialize message in the
// request body (streamable-http only). The framework's async
// `getInitializeRequest()` relies on Durable Object storage which is only
// written after `onStart`/`init()` runs, so on the first connect `init()` has
// no client info to read. Parsing the body here gives `init()` the values
// synchronously via `RequestProperties`.
const clientInfo = await extractClientInfoFromBody(request)
// Streamable-HTTP transport session id, minted by the MCP server on
// initialize and echoed back on every subsequent request. Absent on the
// initialize call itself. Distinct from `sessionId` (above), which is the
// wrapper-app-provided analytics correlation id.
const mcpSessionId = sanitizeHeaderValue(request.headers.get('mcp-session-id') || undefined)
// Agent-echoed conversation id, for wrapper apps that hold one already. Direct clients
// carry it in the `conversation_id` tool argument instead, which the SDK reads in
// `prepareToolCall`. Both land on the same `requestProperties.mcpConversationId` slot.
const mcpConversationId = sanitizeHeaderValue(request.headers.get('mcp-conversation-id') || undefined)
// Anthropic-set per-request identifier for the inner upstream client (e.g.
// `ClaudeCode`, `ClaudeAI`, `Cowork`). Distinct from `mcpClientName` (the
// MCP `initialize` body's `clientInfo.name`) because Claude pools MCP
// transports — the same `mcpSessionId` can carry requests from multiple
// upstream products, and only this header tracks the live one.
const mcpVendorClient = sanitizeHeaderValue(request.headers.get('x-anthropic-client') || undefined)
Object.assign(ctx.props, {
apiToken: token,
userHash: hash(token),
sessionId: sessionId || undefined,
mcpSessionId,
mcpConversationId,
organizationId,
projectId,
clientUserAgent,
mcpConsumer,
mcpClientName: resolveEffectiveClientName(clientInfo.clientName, mcpVendorClient),
mcpClientVersion: clientInfo.clientVersion,
mcpProtocolVersion: clientInfo.protocolVersion,
mcpVendorClient,
requestStartTime: Date.now(),
})
// Search params are used to build up the list of available tools. If no features are provided, all tools are available.
// If features are provided, only tools matching those features will be available.
// Features are provided as a comma-separated list in the "features" query parameter.
// Example: ?features=org,insights
const featuresParam = url.searchParams.get('features')
const features = featuresParam ? featuresParam.split(',').filter(Boolean) : undefined
const toolsParam = url.searchParams.get('tools')
const tools = toolsParam ? toolsParam.split(',').filter(Boolean) : undefined
// Region param is used to route API calls to the correct PostHog instance (US or EU).
// This is set by the wizard based on user's cloud region selection during MCP setup.
const regionParam = url.searchParams.get('region') || undefined
const version = Number(request.headers.get('x-posthog-mcp-version') || url.searchParams.get('v')) || 1
const readOnlyRaw = request.headers.get('x-posthog-read-only') || url.searchParams.get('readonly')
const readOnly = readOnlyRaw === 'true' || readOnlyRaw === '1' || undefined
// Explicit selection between tool-based and CLI-based MCP. Falls back to the
// client-detection logic in `resolveMode` when unset. See `parseMcpMode`.
const mode = parseMcpMode(request.headers.get('x-posthog-mcp-mode') || url.searchParams.get('mode'))
const extraContextProps = { features, tools, region: regionParam, version, readOnly, mode }
Object.assign(ctx.props, extraContextProps)
log.extend(extraContextProps)
if (mcpConsumer) {
log.extend({ mcpConsumer })
}
if (clientInfo.clientName) {
log.extend({ mcpClientName: clientInfo.clientName })
}
// Marker set by the /sse → /mcp redirect handler above. Lets us correlate
// success/failure on this /mcp request back to clients that originated on
// the deprecated /sse path — both in worker logs and in the `mcp init`
// analytics event (via `RequestProperties.viaSseRedirect`).
const viaSseRedirect = url.searchParams.get('_deprecated') === 'sse'
if (viaSseRedirect) {
log.extend({ via: 'sse_redirect' })
Object.assign(ctx.props, { viaSseRedirect: true })
}
if (url.pathname.startsWith('/mcp')) {
const region = await resolveProxyRegion(token, ctx.props.userHash, env.MCP_KV)
log.extend({ proxy: 'hono', region })
const response = await proxyToHono(request, region)
const authError = isRejectedTokenChallenge(response)
? 'rejected_token'
: isInsufficientScopeChallenge(response)
? 'insufficient_scope'
: undefined
if (authError) {
log.extend({ authError })
return withResourceMetadata(response, request, effectiveRegion)
}
return response
}
log.extend({ error: 'route_not_found' })
return new Response('Not found', { status: 404 })
}
// Worker entry point
export default {
fetch: withLogging(handleRequest),
}