tollbooth-oauth2-collector

Tollbooth OAuth2 Collector

一个无需身份验证的“简易邮箱” FastMCP 服务，用于存放 OAuth2 授权码，供发起请求的 MCP 服务取回。配套的无服务器函数（Val Town）接收来自 OAuth 提供方的浏览器重定向，并将授权码交给此收集器的 store_code MCP 工具。这种两部分设计可以绕过 Horizon 仅代理 /mcp/ 路径上的 POST 流量这一限制——OAuth 提供方发出的浏览器 GET 重定向无法访问 @mcp.custom_route 端点，因此由无服务器回调来搭桥。

工作原理

┌───────────────┐   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 服务 发起 OAuth 流程，并将 redirect_uri 设为无服务器回调函数的 URL。其 state 为 <patron npub>.<operator npub>（SDK 的 pack_oauth_state）
2. 用户 在浏览器中授权；OAuth 提供方将用户重定向到无服务器回调，并附带 ?code=...&state=...
3. 无服务器回调（Val Town）通过 /mcp/ 将授权码 POST 到收集器的 store_code MCP 工具
4. 收集器 使用 NIP-44 将授权码加密封装给 operator npub（SDK 的 encrypt_collector_code），并将其按 patron npub 存储在 Postgres 中（TTL 为 600s）
5. MCP 服务 调用 retrieve_code(state=<patron npub>) MCP 工具，取回加密封装的授权码（仅可读取一次，读取后自动删除）
6. MCP 服务 使用自己的 nsec 解封授权码（decrypt_collector_code），并使用自己的凭据交换获取令牌

收集器还提供 collector_status（待处理授权码数量和 TTL）和 service_status（已部署的构建信息，包括 git sha）这两个免费的 MCP 工具。无服务器回调的源码位于 val/oauth_callback.js。

部署

部署到 Horizon：

fastmcp deploy server.py

在 Horizon 中设置 NEON_DATABASE_URL 环境变量，使其指向你的 Neon Postgres 实例。

DPYC Advocate 身份

此收集器已在 DPYC Social Contract 中注册为 Advocate。使用它的 MCP 服务可向 Oracle 查询其 URL：

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"

无需设置 OAUTH_COLLECTOR_URL 环境变量——节点发现由注册表处理。

请在 OAuth 提供方的开发者门户中注册无服务器回调函数的 URL（而非收集器的 URL）。该回调函数已在 DPYC 注册表中单独注册，名称为 tollbooth-oauth2-callback；SDK 的 begin_oauth 会将其用作 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"

安全模型

• 授权码单独存在时毫无用处——交换授权码需要 client_id 和 client_secret，只有使用该收集器的 MCP 服务持有这些信息
• 静态加密——使用 NIP-44 将授权码加密封装给 state 中携带的 operator npub（SDK 的 encrypt_collector_code）；只有该 operator 对应的 nsec 才能解封，而且 state 本身从不作为密钥
• 公开的 state——state 只携带两个 npub，这些公钥可安全地经由浏览器传递；如果 state 中没有 operator npub，则请求会被拒绝
• 仅读取一次——取回后立即删除授权码（防止重放）
• 短 TTL——过期的授权码会自动清理（600s）
• 不存储机密——收集器永远不会接触客户端凭据或令牌

相关仓库

仓库	描述
tollbooth-dpyc	Tollbooth 变现 Python SDK
dpyc-community	DPYC 社会契约注册表和治理
dpyc-oracle	免费社区顾问服务——会员资格、治理、入门引导
tollbooth-authority	认证机构 MCP 服务
tollbooth-sample	Operator 参考实现 / 模板
tollbooth-pricing-studio	面向 Operator 的 iOS 定价编辑器
cypher-mcp	变现图谱查询——针对 Neo4j/AuraDB 的命名 Cypher
schwab-mcp	Schwab 经纪业务 MCP 服务
thebrain-mcp	个人 Brain 知识图谱 MCP 服务
excalibur-mcp	X（Twitter）发帖 MCP 服务
taxsort-mcp	税务分类和归类 MCP 服务
optionality-mcp	期权分析 MCP 服务
goodearth-mcp	按区域限定的农场气候分析 MCP 服务
beesknees-mcp	The Bee's Knees 多人竞速 MCP 服务
roastify-mcp	Roastify 咖啡目录和包装设计图稿 MCP 服务
ChartRemotely-mcp	桌面图表中继 MCP 服务
tollbooth-web	面向 Operator 前端的共享浏览器 SDK
tollbooth-oauth2-collector	OAuth2 回调收集器（Advocate）
tollbooth-shortlinks	URL 缩短工具（Advocate）

许可证

版权所有 2026 Lonnie VanZandt。根据 Apache License, Version 2.0 授权。