Excalibur MCP

eXcalibur MCP

Sword-swift posting of pretty tweets to X (Twitter) via AI agents, monetized with Bitcoin Lightning micropayments through the DPYC(TM) Tollbooth protocol.

eXcalibur is a FastMCP server that lets AI agents post to X (Twitter) with rich Unicode formatting and optional images. Patron authentication for X uses OAuth2 Authorization Code + PKCE -- no credentials appear in chat. Operator credentials (X app keys, BTCPay) arrive via human-in-the-loop Secure Courier and are stored in the operator's per-operator Neon vault schema. Tool calls are metered with Tollbooth DPYC(TM) pre-funded Lightning balances -- Don't Pester Your Customer.

Part of the DPYC(TM) Social Contract.

Getting Started

Connect via Horizon -- no local install needed:

https://excalibur-mcp.fastmcp.app/mcp

The web editor at https://excalibur.tollbooth-dpyc.com drives the same tools from a browser.

Step 1: Check Session

Call excalibur_session_status to see your current session state. If you have an active session with funded credits, you are ready to post.

Step 2: Prove Your Npub on the Connection

Identity rides on the connection, not on tool arguments. Connecting from an AI assistant is an OAuth holder connection: call excalibur_request_npub_proof(patron_npub= ), reply to the Nostr DM it sends, then call excalibur_receive_npub_proof(patron_npub= , nonce= ) once. The connection then holds your npub for the lifetime you chose in the reply (up to 30 days), and every tool call passes only npub. A caller that holds the nsec may instead sign each HTTP request (NIP-98).

Step 3: X OAuth2 + PKCE (Patron Credentials for X)

1. Get your Nostr npub -- use the dpyc-oracle's how_to_join() tool, or any Nostr client.
2. Call excalibur_begin_oauth(npub= ) -- returns an authorize_url. Open the primary authorize_url (not a shortlink) in your browser and authorize the app on X.
3. Call excalibur_check_oauth_status(npub= ) -- completes the code exchange, vaults the tokens, and activates your session.

Sessions are keyed by npub. Tokens are stored in the Neon vault and auto-refresh on expiry.

Step 4: Secure Courier (Operator Credentials)

Operator credentials (X OAuth2 app keys, BTCPay connection) are delivered via Secure Courier (service="excalibur-operator"). This is a human-in-the-loop flow: the operator consciously approves each credential delivery via their Nostr client. On receive_credentials, the relay DM is destructively drained -- credentials exist only in the Neon vault after receipt.

Credits Model

Tool calls cost api_sats per call. Each purchase creates a tranche; it expires only if the operator's pricing model sets a tranche_lifetime. Auth and balance tools are always free. Use excalibur_check_balance to see your balance and tranche expiry. Top up via excalibur_purchase_credits.

Available Tools

Standard Tools (from the wheel)

Standard DPYC(TM) tools are registered by register_standard_tools() from tollbooth-dpyc. These include session management, credit operations, Secure Courier, pricing, notarization, and Oracle delegation. Each tool is identified by a deterministic UUID v5.

Domain Tools (eXcalibur-specific)

Domain tools are defined in server.py (with storage handlers under tools/). Prices are set by the operator's pricing model -- preview any call with check_price. Read and auth tools are free.

Posting to X

Stored posts (drafts & scheduling)

Snippets & Voice

AI editorial & dynamic blocks

Conversation leads

Post metrics

Scheduler

OAuth flow tools (begin_oauth, check_oauth_status) are now standard tools provided by the wheel (see the Standard Tools table above).

Tools that take an npub take only the npub: the connection proves it (see Security).

Security

• Npub identity -- Patrons are identified by a Nostr public key (npub), not an email or password. One keypair per role, managed by the user.
• Identity on the connection -- A connection proves its npub in one of two ways: each HTTP request is signed with the npub's key (NIP-98, kind 27235), or an OAuth holder connection carries an Operator-signed grant earned through request_npub_proof / receive_npub_proof. The patron chooses the grant's lifetime, up to 30 days; held_identities and check_proof_status show what a connection holds.
• Human-in-the-loop Secure Courier -- Credential delivery requires conscious operator approval via Nostr DM. On receipt, the relay message is destructively drained so secrets exist only in the encrypted Neon vault.
• Per-operator Neon schema -- Each operator's credentials are stored in an isolated Postgres schema with a dedicated LOGIN role. No cross-operator access.

Architecture

src/excalibur_mcp/

server.py FastMCP server -- domain tools + register_standard_tools() config.py Pydantic settings from environment variables oauth_flow.py X-specific OAuth2 Authorization Code + PKCE wrapper x_client.py X API v2 client with OAuth 2.0 Bearer token auth formatter.py Markdown -> Unicode rich text (bold, italic, headers) refine.py Server-side editorial refinement for the post editor resolve.py Server-side resolution of dynamic (prompt-backed) post blocks resolver.py Builds one post's finished body (the slow half: dynamic blocks) publisher.py Carries a finished body to X (the fast half: bill, post, record) scheduler.py Scheduled-post firing (publishes due posts on the owner's behalf) conversation_scoring.py Pure scoring + query composition for conversation leads metrics_harvest.py Post-metrics harvest cadence and derived reach scores nostr_note.py Public Nostr notes signed by an ephemeral scribe key tools/ Domain storage handlers (posts, snippets, voices, conversations, metrics) db/ eXcalibur persistence on the wheel's NeonVault (posts, snippets, voices, conversations, metrics, scheduler runs, migrations) modal_app.py Detached runner for long dynamic-block resolves (Modal) scheduler-worker/ Cloudflare Worker cron that fires due scheduled posts frontend/ The web editor (excalibur.tollbooth-dpyc.com)

Key design choices:

• OAuth2 Authorization Code + PKCE -- Patron tokens acquired via browser flow. begin_oauth returns the primary authorize_url (not a shortlink); check_oauth_status completes the exchange. Tokens stored in Neon vault, auto-refreshed on expiry. No OAuth 1.0a.
• UUID v5 tool identity -- Every tool (standard and domain) has a deterministic UUID derived from its capability name. Pricing, constraints, and billing all key on UUID.
• Standard tools from the wheel -- register_standard_tools() provides all DPYC(TM) infrastructure tools. Only domain-specific X/Twitter tools are defined in server.py.