Tollbooth Oauth2 Collector

io.github.lonniev由 GitHub 账号 lonniev 发布v0.2.12更新于 Oct 26, 2026

Unauthenticated OAuth2 callback collector for Tollbooth MCP services

已验证Streamable HTTP可网页运行开发者工具安全与监控

概览

AI 生成的概览

一个无需认证的中转服务,暂存浏览器回调送来的已封装 OAuth2 授权码,供发起方 MCP 服务器一次性取回。

可以做什么
  • 存储无服务器回调在浏览器重定向后提交的已封装 OAuth2 授权码,以 state 中的 patron npub 为键。
  • 供发起方 MCP 服务器一次性取回授权码,读取后立即删除。
  • 查看收集器健康状态,显示待处理授权码数量与 TTL。
  • 报告当前运行的构建版本,便于确认重新部署是否生效。
适用场景
仅当你运营或使用某个 Tollbooth MCP 服务,且其 OAuth 提供方的重定向无法直接到达 MCP 端点、需要回调桥接时才相关。多数助手和终端用户没有添加它的必要。
运行要求
远程 streamable HTTP 端点,无需本地安装。托管实例依赖 Postgres 数据库(NEON_DATABASE_URL)以及一个注册为 OAuth 重定向 URI 的配套 Cloudflare Worker。调用方服务器通过 DPYC Oracle 发现其地址。
安装前请注意
端点无需认证,任何知道 patron npub 与 state 的人都能为其存取授权码;授权码以 operator npub 封装,只有持有该 operator 的 nsec 才能解开。授权码为一次性读取,TTL 为 600 秒。收集器本身不接触客户端凭据或令牌,但 operator 私钥保存在调用方服务器上,必须妥善保护。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Tollbooth Oauth2 Collector,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.lonniev%2Ftollbooth-oauth2-collector/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "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.

来源:README.md,提交 3f2dbdb

工具

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.

输入参数code必填state必填

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.

输入参数state必填

collector_status

Collector Status

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

无需输入参数。

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.

无需输入参数。

版本历史

2
  1. v0.2.12最新Oct 21, 2026
  2. v0.2.11Sep 16, 2026

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分