personalbrain-mcp

thebrain-mcp

Lightning Turnpike 最初の都市。

AI エージェントに個人のナレッジグラフへの読み書きアクセスを提供し、Bitcoin Lightning のマイクロペイメントで自らの費用を賄う MCP サーバーです。

このプロジェクトの比喩は、Norton Juster 作、Jules Feiffer 挿絵の The Phantom Tollbooth (1961) に敬意を込めて着想を得ています。Milo、Tock、Tollbooth、Dictionopolis、Digitopolis は、Juster 氏の並外れた想像力から生まれたものです。私たちは決済インフラを構築しただけです。

---

最初の都市

どんなターンパイクにも、最初の都市が必要です。料金所が通行料を徴収し、当局が購入注文書に印を押せるようになる前に、誰かが訪れる価値のある目的地を築かなければなりません。

thebrain-mcp はその都市です。TheBrain という、10 年かけて構築された 9,000 件以上の相互接続された思考からなる個人のナレッジグラフと AI エージェントをつなぐ、Horizon にデプロイされた FastMCP サービスです。思考、リンク、添付ファイル、ノートに関するすべての操作は、api.bra.in の TheBrain クラウド API に直接対応しています。

また、Tollbooth DPYC™ の実証の場でもあります。すべてのツール呼び出しに Bitcoin Lightning のマイクロペイメントを適用する、初の MCP サーバーです。事前入金して利用し、必要に応じてチャージします。サブスクリプションも、課金アカウントにひも付いた API キーも、法定通貨の決済処理業者も必要ありません。独自の貢献は、会話の途中でクライアントに決済を催促することなく、運営者が Lightning のマイクロペイメントを通じて AI エージェントのアクセスを収益化する MCP サーバーアーキテクチャです。

はじめに

Horizon MCP 経由で接続する

MCP 互換クライアント（Claude Desktop、Cursor、ご自身のエージェントなど）を、稼働中のエンドポイントに接続します。

https://personal-brain.fastmcp.app/mcp

設定は不要です。クライアントは OAuth で接続します。接続には最初 npub が含まれませんが、Nostr DM に返信して証明することで接続に登録できます（request_npub_proof の後に receive_npub_proof を実行します）。nsec を保持するクライアントは、代わりに各リクエストに署名し（NIP-98）、DM は必要ありません。その後、ツールに必要なのは npub だけです。

初回接続の手順

1. session_status — 現在のセッション状態を確認します。
2. dpyc-oracle の how_to_join() ツールから、パトロンの npub を取得します。これは DPYC™ シチズンとして登録した npub で、クレジット操作に使用する本人識別情報です。
3. Secure Courier のオンボーディング：
   • request_credential_channel(sender_npub=<patron_npub>, service=<service>) を呼び出します。Secure Courier チャネルが開き、Nostr クライアントにウェルカム DM が送られ、チャネルの nonce が返されます。
   • Nostr クライアントから、認証情報を JSON 形式で返信します：{"api_key": "...", "brain_id": "..."}
   • receive_credentials(sender_npub=<patron_npub>, service=<service>, nonce=<that nonce>) を呼び出します。認証情報が保管庫に格納され、セッションが有効になります。初期残高は自動的に付与されます。
4. list_brains → set_active_brain — 作業対象のブレインを選択します。
5. brain_query — ナレッジグラフを探索します。

再訪ユーザーは、この手順を繰り返す必要はありません。初回利用時に、保管庫からセッションが復元されます。

Secure Courier

認証情報は暗号化された Nostr DM 経由で届けられるため、チャットウィンドウに表示されることはありません。リレーで初めて受信すると、サービスは ncred1... 認証情報カードを DM 経由で利用者に送り返します。これをスキャンして貼り付けることで再利用できます。

**人間が介在します：**利用者は、Nostr クライアントを使って認証情報の配信を毎回明示的に承認する必要があります。receive_* 呼び出しを自動でポーリングしたり再試行したりしないでください。receive_credentials を呼び出すと、リレーの内容は破壊的に消費されます（受信後に NIP-09 による削除が行われます）。認証情報の配信ごとに、必ず 1 回だけ呼び出してください。

クレジットモデル

カテゴリ	価格の目安	例
free	0 sats	session_status、check_balance、check_price
read	1 sat	get_thought、search_thoughts、get_note
write	5 sats	create_thought、create_link、update_thought
heavy	10 sats	brain_query、get_modifications

実際の価格は、オペレーターが Neon で各ツールの api_sats に設定する価格モデルに応じて動的に決まります。認証ツールと残高確認ツールは常に無料です。初回利用者にはオンボーディング時にシード残高が付与されるため、クレジットを事前購入せずにサービスを試せます。

クレジットは tranche_lifetime（TTL）が設定されたトランシェ単位で発行されます。トランシェは FIFO 順に消費され、期限切れのトランシェは自動的に削除されます。check_balance を使うと、残高、有効なトランシェ、利用履歴を確認できます。Bitcoin Lightning を使って purchase_credits からチャージしてください。

セキュリティ

• ID は Nostr のキーペアです — ユーザーはメールアドレスやユーザー名ではなく、npub（Nostr 公開鍵）で識別されます。nsec（秘密鍵）は利用者が保持し、共有もサービスへの送信もされません。
• 証明は kind-27235 の Schnorr 署名付き NIP-98 イベントです — 有料ツールにはすべて proof パラメーターが必要です。証明は、利用者の nsec で署名された JSON シリアライズ形式の Nostr イベントであり、利用者の npub を特定のツール呼び出しに紐付けます。
• 人間が介在します — 利用者は Nostr クライアントを使って証明に署名する必要があります。エージェントが証明を自動生成したり、キャッシュしたりすることはありません。証明キャッシュ（v0.9.2 以降、Vault に保存）は検証済みの証明を約 1 時間保持します。更新するには、新たにリクエストと受信のサイクルを行う必要があります。
• Secure Courier 経由の認証情報 — TheBrain API キーとブレイン ID は、NIP-44 で暗号化された Nostr DM 経由で届けられ、Neon Postgres に保管されます。チャットウィンドウに表示されることはありません。

BrainQuery（BQL）

TheBrain 専用に設計された、Cypher のサブセットに基づくクエリ言語です。エージェントも人間も同じ形式でグラフ操作を表現でき、MATCH、CREATE、SET、MERGE、DELETE による CRUD 操作をすべてサポートします。

MATCH (n {name: "Projects"})-[:CHILD]->(m) RETURN m
MATCH (n) WHERE n.name =~ "quarterly review" RETURN n
MATCH (p {name: "Ideas"}) CREATE (p)-[:CHILD]->(n {name: "New Concept"})
MATCH (root {name: "Company"})-[:CHILD*1..3]->(d) WHERE d.name CONTAINS "Budget" RETURN d

可変長パス、複数ホップのチェーン、AND／OR／NOT／XOR を使った複合 WHERE、類似検索、プロパティの存在確認に対応しています。文法の全容は BRAINQUERY.md を参照してください。

トラブルシューティング

ツール呼び出しが失敗した場合は、応答を読んでください。何が起きたのか、次に何をすべきかが示されています。認証情報のライフサイクル状態はエラーではなく、明確な対処方法がある想定内の状況です。

状況	対処方法
proof が必要です	request_npub_proof を呼び出してから receive_npub_proof を呼び出し、新たにリクエストと受信のサイクルを行ってください。キャッシュは約 1 時間で期限切れになります。
クレジット残高が不足しています	purchase_credits を呼び出してチャージしてください。
コールドスタート／セッションの準備ができていません	10～15 秒後に再試行してください。v0.13.5 以降では、インライン再試行が利用できます。
認証情報が見つかりません	Secure Courier のオンボーディングフロー（上記のステップ 3）に従ってください。
上流 API エラー	エラーに TheBrain API の失敗が明記されている場合に限ります。認証情報や請求の問題ではありません。

**利用者にしつこく求めないでください：**エラーメッセージに認証情報の欠落または期限切れが明記されている場合を除き、利用者に再認証や Courier フローのやり直しを求めないでください。

セルフホスティング

ローカルへのインストールとセットアップについては、INSTALL.md および QUICKSTART.md を参照してください。

独自のインスタンスを実行するには、次の環境変数を設定してください。

必須

変数	用途
TOLLBOOTH_NOSTR_OPERATOR_NSEC	オペレーターのNostr秘密鍵 — ID、Secure Courier DM、監査署名に使用する唯一のブートストラップ鍵

起動に必要な環境変数はこれだけです。認定オペレーターは、暗号化されたNostr DMを介してAuthorityからNeonデータベースのURLを取得します。NEON_DATABASE_URLは環境変数から読み込まれません。

任意の調整項目

変数	用途
TOLLBOOTH_NOSTR_RELAYS	カンマ区切りのリレーURL（デフォルトを上書きします）
THEBRAIN_API_URL	TheBrain APIのベースURL（デフォルト：https://api.bra.in）
SEED_BALANCE_SATS	新規ユーザー向けの無料初期残高（0にすると無効になります）
CREDIT_TTL_SECONDS	トランシェの有効期間（秒）（デフォルト：604800 = 7日）
DPYC_REGISTRY_CACHE_TTL_SECONDS	DPYCコミュニティレジストリのキャッシュ期間（デフォルト：300）
CONSTRAINTS_ENABLED	ツール呼び出し時の制約エンジン評価を有効にするには"true"を指定します

Secure Courier経由の認証情報（環境変数ではありません）

すべてのシークレットはSecure Courier経由で送信され、環境変数として設定されることはありません。

認証情報	送信方法
TheBrain APIキーとbrain ID	パトロンが暗号化されたNostr DM経由で送信します
BTCPay認証情報（btcpay_host、btcpay_api_key、btcpay_store_id）	オペレーターがSecure Courier経由で送信します

注： THEBRAIN_API_KEYは環境変数ではありません。パトロンはSecure Courier（暗号化されたNostr DM）経由でTheBrain APIキーとbrain IDを送信します。環境変数として設定するのは、オペレーターのnsecのみです。

ツールの構成

サーバーは、tollbooth-dpycのregister_standard_tools()を介して標準のTollbooth DPYC™オペレーター向けツールを公開するほか、ドメイン固有のツールも提供します。DPYCの3者トポロジー（Operator／Authority／Oracle）において、ツールは次の3つの経路に分類されます。

経路	ツール	状態
ホット（ローカル台帳）	check_balance、account_statement、account_statement_infographic、restore_credits、service_status	実装済み — server.pyに委譲します
ホット（Secure Courier）	session_status、request_credential_channel、receive_credentials、forget_credentials	実装済み — 資格情報カードDMを含むNostr経由の資格情報送信
委譲（Authority）	purchase_credits、check_payment	実装済み — MCP間通信を介して自動認定します
委譲（Authority）	certify_credits、operator_status	スタブ — Authority MCPに直接接続してください
委譲（Oracle）	lookup_member、how_to_join、get_tax_rate、about、network_advisory	実装済み — OracleClient経由のMCP間通信

決済処理ではAuthorityを介して自動認定されます（サーバー間OAuth）。Secure Courierは、Nostr DMを介して暗号化された認証情報を送信し、初回受信時には資格情報カード（ncred1...）を自動的にDMで返信します。OracleコミュニティツールはDPYC™ Oracleに直接ルーティングされ、無料で認証も不要です。

アーキテクチャ

Tollbooth DPYC™エコシステムは、3つのリポジトリにまたがる3者間プロトコルです。

リポジトリ	役割
tollbooth-authority	機関 — 税の徴収、Schnorr署名、購入注文の認定
tollbooth-dpyc	ブース — オペレーター側のクレジット台帳、BTCPayクライアント、ツールのゲーティング
dpyc-oracle	コンシェルジュ — コミュニティへのオンボーディング、税率、会員照会
thebrain-mcp（このリポジトリ）	最初の都市 — Tollbooth DPYC™を基盤とするリファレンスMCPサーバー

全体のアーキテクチャについては、Three-Party Protocol diagramを参照してください。オペレーター側のフローも確認できます。

プロジェクト構成

thebrain-mcp/
├── src/thebrain_mcp/        # Server source, BQL engine, Tollbooth
├── tests/                   # Test suite (465+ tests)
├── fastmcp.json             # Horizon deploy entrypoint (src/thebrain_mcp/server.py)
├── pyproject.toml           # Package metadata and dependencies
├── BRAINQUERY.md            # BQL grammar and reference
├── INSTALL.md / QUICKSTART.md  # Local install and setup
├── docs/diagrams/           # Architecture and protocol flow diagrams
├── LICENSE                  # Apache License 2.0
└── NOTICE                   # Attribution notice

先行技術と帰属表示

このリポジトリに含まれる手法、アルゴリズム、実装は、Lonnie VanZandt による独自の成果である可能性があり、2026年2月16日に初めて公開されました。この公開により、米国特許法（35 U.S.C. 102）に基づく先行技術が確立されます。

すべての使用、複製、派生著作物は、このリポジトリに含まれる Apache License 2.0 に準拠し、NOTICE ファイルに従って原作者を適切に表示する必要があります。

帰属表示の方法

この成果を使用または発展させる場合は、ドキュメントまたはソースに以下を記載してください。

Based on original work by Lonnie VanZandt and Claude.ai
Originally published: February 16, 2026
Source: https://github.com/lonniev/thebrain-mcp
Licensed under Apache License 2.0

Bitcoin 支持者やコーヒー愛好家のための、技術者のオンラインカフェは stablecoin.myshopify.com からご覧ください。

特許に関する通知

著者は、ここに記載された新規な手法およびシステムについて、特許保護を求めるすべての権利を留保します。この成果の公開により、2026年2月16日が優先日として確立されます。America Invents Act に基づき、著者は初回公開日から1年間の猶予期間内に特許出願を行う権利を保持します。

出願を検討している方への注意： この公開リポジトリと完全な Git 履歴は、先行技術の証拠となります。このリポジトリの公開日以降に出願され、実質的に類似する手法を対象とする特許出願は、35 U.S.C. 102(a) に基づき無効となる可能性があります。

DPYC™ エコシステム

• tollbooth-dpyc — Python SDK（ボールト、認証、料金設定、Lightning、Nostr ID）
• dpyc-community — ガバナンスレジストリ：メンバーシップ、勧告、脅威モデル
• dpyc-oracle — コミュニティコンシェルジュ（無料のオンボーディングとメンバー検索）
• tollbooth-authority — 認証基盤（Schnorr 署名付き証明書）
• tollbooth-sample — サンプルオペレーター（標準テンプレート）
• tollbooth-pricing-studio — iOS 料金モデルエディター／オペレーターコンソール
• cypher-mcp — 収益化されたグラフ回答：Neo4j/AuraDB 上の名前付き Cypher テンプレート
• schwab-mcp — Charles Schwab の証券口座データ
• thebrain-mcp — TheBrain の個人ナレッジグラフ
• excalibur-mcp — X/Twitter への投稿
• taxsort-mcp — 税務分類と Cloudflare Pages UI
• optionality-mcp — オプション分析（証券口座データオペレーター）
• tollbooth-oauth2-collector — OAuth2 コールバックハンドラー（支持者向けサービス）
• tollbooth-shortlinks — URL 短縮ユーティリティ

さらに読む

The Phantom Tollbooth on the Lightning Turnpike — AI API の収益化をさらに収益化し、その後は背景に退いていく方法を語る全編です。

商標

DPYC™、Tollbooth DPYC™、Don't Pester Your Customer™ は Lonnie VanZandt の商標です。使用ガイドラインについては、dpyc-community リポジトリの TRADEMARKS.md をご覧ください。

ライセンス

Apache License 2.0 — 詳細は LICENSE と NOTICE をご覧ください。

---

結局のところ、料金所は目的地ではありませんでした。いつだって、旅の始まりにすぎなかったのです。