Personalbrain MCP server

thebrain-mcp

The first city on the Lightning Turnpike.

An MCP server that gives AI agents read-write access to a personal knowledge graph — and pays for itself with Bitcoin Lightning micropayments.

The metaphors in this project are drawn with admiration from The Phantom Tollbooth by Norton Juster, illustrated by Jules Feiffer (1961). Milo, Tock, the Tollbooth, Dictionopolis, and Digitopolis are creations of Mr. Juster's extraordinary imagination. We just built the payment infrastructure.

The First City

Every turnpike needs its first city. Before the booths can collect fares and the authority can stamp purchase orders, someone has to build a destination worth driving to.

thebrain-mcp is that city — a FastMCP service deployed on Horizon that bridges AI agents to TheBrain, a personal knowledge graph of 9,000+ interconnected thoughts built over a decade. Every thought, link, attachment, and note operation maps directly to TheBrain's cloud API at api.bra.in.

It's also the proving ground for Tollbooth DPYC™ — the first MCP server where every tool call is metered via Bitcoin Lightning micropayments. Pre-fund, use, top up. No subscriptions, no API keys tied to billing accounts, no fiat payment processors. The novel contribution: an MCP server architecture where the operator monetizes AI agent access through Lightning micropayments without ever pestering the client mid-conversation.

Getting Started

Connecting via Horizon MCP

Connect any MCP-compatible client (Claude Desktop, Cursor, your own agent) to the live endpoint:

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

No configuration needed — Horizon OAuth handles authentication automatically.

First Connection Walkthrough

1. sessionstatus** — Check your current session state.
2. Get your patron npub from the dpyc-oracle's howtojoin() tool — this is the npub you registered as a DPYC™ Citizen, your identity for credit operations.
3. Secure Courier onboarding:

• Call requestcredentialchannel(recipient_npub=) — opens a Secure Courier channel; sends a welcome DM to your Nostr client.
• Reply via your Nostr client with your credentials in JSON: {"apikey": "...", "brainid": "..."}
• Call receivecredentials(sendernpub=) — vaults your credentials and activates the session. A seed balance is granted automatically.

1. listbrains → setactivebrain** — Select which brain to work with.
2. brainquery** — Start exploring your knowledge graph.

Returning users: call receivecredentials(sendernpub=) — vault-first lookup activates instantly, no relay I/O needed.

Secure Courier

Credentials are delivered via encrypted Nostr DMs — they never appear in the chat window. On first-time relay receipt, the service sends an ncred1... credential card back to the patron via DM for scan-and-paste reuse.

Human in the loop: The patron must consciously approve each credential delivery via their Nostr client. Never auto-poll or auto-retry receive calls — each receivecredentials drains the relay destructively (NIP-09 deletion after pickup). Call it exactly once per credential delivery.

Credits Model

Shortened. The full README is on GitHub.