Tollbooth OAuth2 Collector

An unauthenticated "dumb mailbox" FastMCP server that holds OAuth2 authorization codes for retrieval by the originating MCP server. A companion serverless function (Val Town) 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 a serverless callback bridges the gap.

How It Works

┌───────────────┐   1. redirect_uri → serverless    ┌──────────────────────┐
│ OAuth Provider│ ─────────────────────────────────→│ Serverless callback  │
│ (e.g. Schwab) │   GET ?code=AUTH_CODE&state=STATE  │ (Val Town)           │
└───────────────┘                                    └──────────────────────┘
                                                               │
                                        2. POST store_code     │
                                           (JSON-RPC /mcp/)     ▼
                                                     ┌──────────────────────┐
                                                     │ OAuth2 Collector     │
                                                     │ store_code tool      │
                                                     │ → seals + Postgres   │
                                                     └──────────────────────┘
                                                               │
                                                               │ 3. code stored
                                                               ▼
┌──────────────┐   4. retrieve_code(state=PATRON)    ┌──────────────────────┐
│ MCP Server   │ ─────────────────────────────────→  │ OAuth2 Collector     │
│ (e.g.        │        (JSON-RPC /mcp/)             │ retrieve_code tool   │
│  schwab-mcp) │ ←───────────────────────────────── │ → returns code once  │
└──────────────┘   {"found": true, "code": ...}      │ → deletes from DB    │
                                                     └──────────────────────┘

1. 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)

2. User authorizes in the browser; the OAuth provider redirects to the serverless callback with ?code=...&state=...

3. Serverless callback (Val Town) POSTs the code to the collector's store_code MCP tool over /mcp/

4. 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)

5. MCP server calls the retrieve_code(state=<patron npub>) MCP tool to pick up the sealed code (one-time read, auto-deleted)

6. 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 serverless callback source lives in val/oauth_callback.js. A change to it on main deploys it to Val Town (.github/workflows/deploy-val-town.yml, which needs the VALTOWN_TOKEN secret).

Related MCP server: MCP Credentials Broker

Deployment

Deploy to Horizon:

fastmcp deploy server.py

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:

from tollbooth.oracle_client import default_oracle_client

svc = await default_oracle_client().resolve_service(name="tollbooth-oauth2-collector")
collector_url = svc["url"]  # e.g., "https://tollbooth-oauth2-collector.fastmcp.app"

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:

callback = await default_oracle_client().resolve_service(name="tollbooth-oauth2-callback")
redirect_uri = callback["url"]  # e.g., "https://tollbooth-dpyc-oauth.val.run"

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.