tollbooth-oauth2-collector

Tollbooth OAuth2 Collector

認証を必要としない「単純なメールボックス」として機能し、元の MCP サーバーが取得できるよう OAuth2 認可コードを保持する FastMCP サーバーです。付属のサーバーレス関数（Val Town）が OAuth プロバイダーからのブラウザーリダイレクトを受け取り、コードをこのコレクターの store_code MCP ツールに渡します。この2つの部分からなる設計により、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/ 経由でコードをコレクターの store_code MCP ツールに POST します。
4. コレクターが NIP-44 でコードを operator npub 宛てに封印し（SDK の encrypt_collector_code）、patron npub に紐付けて Postgres に保存します（TTL は600秒）。
5. MCP サーバーが retrieve_code(state=<patron npub>) MCP ツールを呼び出し、封印されたコードを取得します（1回限りの読み取り後、自動削除）。
6. MCP サーバーが自身の nsec で封印を開き（decrypt_collector_code）、自身の認証情報を使ってコードをトークンと交換します。

コレクターは、無料の MCP ツールとして collector_status（保留中のコード数と TTL）および service_status（デプロイ済みビルド。git sha を含む）も公開します。サーバーレスコールバックのソースは val/oauth_callback.js にあります。

デプロイ

Horizon にデプロイします。

fastmcp deploy server.py

Horizon で NEON_DATABASE_URL 環境変数を設定し、Neon Postgres インスタンスを指定します。

DPYC Advocate Identity

このコレクターは 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 を登録してください。この関数は DPYC レジストリに tollbooth-oauth2-callback という名前で別途登録されており、SDK の begin_oauth はこの URL を 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 サーバーだけが保持します。
• 保存時に封印 — コードは state に含まれる operator npub 宛てに NIP-44 で封印されます（SDK の encrypt_collector_code）。封印を開けられるのはその operator の nsec だけで、state が鍵として使われることはありません。
• 公開 state — state に含まれるのは2つの npub のみです。これらはブラウザー経由でルーティングしても安全な公開鍵です。operator npub を含まない state は拒否されます。
• 1回限りの読み取り — 取得後、コードは直ちに削除されます（リプレイを防止）。
• 短い TTL — 期限切れのコードは自動的にクリーンアップされます（600秒）。
• シークレットを保存しません — コレクターがクライアント認証情報やトークンを参照することはありません。

関連リポジトリ

リポジトリ	説明
tollbooth-dpyc	Tollbooth の収益化向け Python SDK
dpyc-community	DPYC ソーシャルコントラクトのレジストリとガバナンス
dpyc-oracle	無料のコミュニティコンシェルジュ — メンバーシップ、ガバナンス、オンボーディング
tollbooth-authority	認証局 MCP サービス
tollbooth-sample	オペレーター実装のリファレンス／テンプレート
tollbooth-pricing-studio	オペレーター向け iOS 料金設定エディター
cypher-mcp	収益化されたグラフ回答 — Neo4j/AuraDB 上の名前付き Cypher
schwab-mcp	Schwab 証券 MCP サーバー
thebrain-mcp	個人向けブレイン・ナレッジグラフ 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	オペレーターのフロントエンド向け共有ブラウザー SDK
tollbooth-oauth2-collector	OAuth2 コールバックコレクター（Advocate）
tollbooth-shortlinks	URL 短縮ユーティリティ（Advocate）

ライセンス

Copyright 2026 Lonnie VanZandt. Apache License, Version 2.0 の下でライセンスされています。