Tollbooth Oauth2 Collector

io.github.lonnievPublished by GitHub account lonnievv0.2.12Updated Oct 26, 2026

Unauthenticated OAuth2 callback collector for Tollbooth MCP services

VerifiedStreamable HTTPWeb executableDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

An unauthenticated relay that stores sealed OAuth2 authorization codes from a browser callback so the originating MCP server can pick them up once.

What you can do
  • Store a sealed OAuth2 authorization code posted by a serverless callback after the browser redirect, keyed by the patron npub in the state.
  • Retrieve a stored code once for the originating MCP server; the entry is deleted on read.
  • Check collector health, showing the number of pending codes and the TTL.
  • Report the running build so a redeploy can be verified.
When to use it
Only relevant if you operate or consume a Tollbooth MCP service whose OAuth provider redirects cannot reach the MCP endpoint directly and need a callback bridge. Most assistants and end users have no reason to add it.
Requirements
Remote streamable HTTP endpoint; nothing to install locally. The hosted instance depends on a Postgres database (NEON_DATABASE_URL) and a companion Cloudflare Worker registered as the OAuth redirect URI. Consuming servers discover its URL through the DPYC Oracle.
Before you install
The endpoint is unauthenticated, so anyone who knows a patron npub and state can store or fetch codes for it; codes are sealed to the operator npub and readable only with that operator's nsec. Codes are one-time reads with a 600-second TTL. The collector never sees client credentials or tokens, but the operator private key stays with the consuming server and must be protected.

Installation

In SourceWeft

  1. Open Tollbooth Oauth2 Collector in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.lonniev%2Ftollbooth-oauth2-collector/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "tollbooth-oauth2-collector": {
      "type": "http",
      "url": "https://tollbooth-oauth2-collector.fastmcp.app/mcp"
    }
  }
}

README

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

┌───────────────┐   1. redirect_uri → serverless    ┌──────────────────────┐│ OAuth Provider│ ─────────────────────────────────→│ Serverless callback  ││ (e.g. Schwab) │   GET ?code=AUTH_CODE&state=STATE  │ (Cloudflare Worker)  │└───────────────┘                                    └──────────────────────┘                                                               │                                        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. Callback Worker 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 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:

bash
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:

python
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:

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

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

RepositoryDescription
tollbooth-dpycPython SDK for Tollbooth monetization
dpyc-communityDPYC Social Contract registry and governance
dpyc-oracleFree community concierge — membership, governance, onboarding
tollbooth-authorityCertification Authority MCP service
tollbooth-sampleReference Operator implementation / template
tollbooth-pricing-studioiOS pricing editor for Operators
cypher-mcpMonetized graph answers — named Cypher over Neo4j/AuraDB
schwab-mcpSchwab brokerage MCP server
thebrain-mcpPersonal Brain knowledge-graph MCP server
excalibur-mcpX (Twitter) posting MCP server
taxsort-mcpTax sorting and classification MCP server
optionality-mcpOptions analytics MCP server
goodearth-mcpRegion-scoped farm climate analytics MCP server
beesknees-mcpThe Bee's Knees multiplayer race MCP server
roastify-mcpRoastify coffee catalog and packaging artwork MCP server
ChartRemotely-mcpDesktop chart relay MCP server
tollbooth-webShared browser SDK for operator front ends
tollbooth-oauth2-collectorOAuth2 callback collector (Advocate)
tollbooth-shortlinksURL shortener utility (Advocate)

License

Copyright 2026 Lonnie VanZandt. Licensed under the Apache License, Version 2.0.

Source: README.md at commit 3f2dbdb

Tools

4

store_code

Store Code

Store a sealed OAuth2 authorization code. Called by the serverless callback function after the browser redirect. The ``state`` carries BOTH the patron npub (the lookup/retrieve key) and the operator npub (the PUBLIC key the code is sealed to) — see the SDK's ``pack_oauth_state``. The code is sealed with NIP-44 to the operator so only that operator's nsec can open it; the Neon row is keyed by the patron npub, so retrieval (``retrieve_code(state=patron_npub)``) is unchanged.

Parameterscoderequiredstaterequired

retrieve_code

Retrieve Code

Retrieve a stored authorization code (one-time read, auto-deleted). Called by the originating MCP server to pick up the code after the user has authorized in the browser. Returns the encrypted code which the caller decrypts using the same state token.

Parametersstaterequired

collector_status

Collector Status

Health check — shows the number of pending authorization codes and TTL.

Takes no parameters.

service_status

Service Status

Report the running build so a redeploy can be verified. Free. Delegates to the SDK's canonical ``build_service_status`` — the single source of the service_status payload shape — so this collector reports the same envelope as every other DPYC service. The load-bearing field is ``build_info.fastmcp_cloud_git_commit_sha``: the commit Horizon actually deployed. The post-merge deploy-verify probe reads it to confirm the live service redeployed the merged sha; with no ``service_status`` tool to probe, that sha reads as ``<none>`` and an otherwise-healthy deploy is flagged as "did not land". The vault/courier/operator fields are ``False``/empty by construction — this is an unauthenticated community utility with no operator runtime.

Takes no parameters.

Version history

2
  1. v0.2.12LatestOct 21, 2026
  2. v0.2.11Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts