Tollbooth OAuth2 Collector
[License]
[Python]
An unauthenticated "dumb mailbox" FastMCP server that holds OAuth2 authorization codes for retrieval by the originating MCP server. A companion Cloudflare Worker receives the browser redirect from the OAuth provider and hands the code to this collector's store_code MCP tool. This two-part design works around Horizon proxying only POST traffic on the /mcp/ path — browser GET redirects from OAuth providers cannot reach @mcp.custom_route endpoints, so the Worker bridges the gap.
How It Works
- MCP server starts an OAuth flow, setting
redirect_uri to the serverless callback function's URL. Its state is <patron npub>.<operator npub> (the SDK's pack_oauth_state)
- User authorizes in the browser; the OAuth provider redirects to the serverless callback with
?code=...&state=...
- Callback Worker POSTs the code to the collector's
store_code MCP tool over /mcp/
- Collector seals the code to the operator npub with NIP-44 (the SDK's
encrypt_collector_code) and stores it in Postgres under the patron npub (600s TTL)
- MCP server calls the
retrieve_code(state=<patron npub>) MCP tool to pick up the sealed code (one-time read, auto-deleted)
- MCP server opens the seal with its own nsec (
decrypt_collector_code) and exchanges the code for a token using its own credentials
The collector also exposes collector_status (pending-code count and TTL) and service_status (deployed build, incl. git sha) as free MCP tools. The callback source lives in worker/oauth_callback.js. A change to it on main deploys it to https://oauth.tollbooth-dpyc.com (.github/workflows/deploy-worker.yml, which needs the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets).
Deployment
Deploy to Horizon:
Set the NEON_DATABASE_URL environment variable in Horizon to point to your Neon Postgres instance.
DPYC Advocate Identity
This collector is registered as an Advocate in the DPYC Social Contract. Consuming MCP servers discover its URL by asking the Oracle:
No OAUTH_COLLECTOR_URL env var needed — peer discovery is handled by the registry.
Register the serverless callback function's URL (not the collector's) in your OAuth provider's developer portal. It is registered separately in the DPYC registry under the name tollbooth-oauth2-callback, and the SDK's begin_oauth uses it as the redirect_uri:
Security Model
- Auth codes are useless alone — exchanging a code requires
client_id + client_secret, held only by the consuming MCP server
- Sealed at rest — codes are sealed with NIP-44 to the operator npub carried in the state (the SDK's
encrypt_collector_code); only that operator's nsec opens them, and the state is never a key
- Public state — the state carries only two npubs, public keys that are safe to route through the browser; a state with no operator npub is refused
- One-time read — codes are deleted immediately after retrieval (prevents replay)
- Short TTL — expired codes are automatically cleaned up (600s)
- No secrets stored — the collector never sees client credentials or tokens
Related Repositories
License
Copyright 2026 Lonnie VanZandt. Licensed under the Apache License, Version 2.0.