@capxul/mcp

The Capxul MCP server — a runnable Model Context Protocol server that exposes Capxul's agent-facing financial-ops tools to MCP clients (Claude, Cursor, and other agents) over Streamable HTTP.

This package ships a CLI, not a library: the published artifact is the capxul-mcp executable.

Install & run

# one-off, via npx
npx @capxul/mcp serve --mode live

# or install globally
npm i -g @capxul/mcp
capxul-mcp serve --mode live

Usage:
  capxul-mcp serve [--mode live|dev] [--port <port>] [--approval-url <url>]

Options:
  --mode live|dev       Launch mode. Defaults to live. There is no env-var mode selector.
  --port <port>         Bind port. Defaults to CAPXUL_MCP_PORT or 8788.
  --approval-url <url>  Approval app base URL. Defaults to CAPXUL_MCP_APPROVAL_URL or http://localhost:5998.
  --help                Show this help.

The server speaks MCP over Streamable HTTP at POST /mcp. The startup banner prints the bound URL and the enabled tool set.

What it exposes

Agent-facing financial-ops tools, composed in src/registry.ts:

• system.ping — liveness probe (no auth, no secrets).
• auth.* — request/verify an email OTP, exchanging it for an opaque session token bound to the MCP session.
• account.* — account readiness and on-chain Money balances.
• faucet.fundTestnet — testnet faucet (env-gated).
• payments.send — send a sponsored stablecoin payment.

Auth & transport

• Streamable HTTP transport — a fresh, stateless McpServer per POST /mcp.
• OAuth bearer auth — an in-memory PKCE OAuth provider gates tool access when CAPXUL_MCP_OAUTH_REQUIRED=1; a proof-issuer secret can mint bearer tokens for automated probes.
• Dev-mode custody gate — --mode dev runs against a deterministic dev signer seed (CAPXUL_MCP_DEV_SIGNER_SEED) so journeys can be exercised without live custody; --mode live uses the production signer path.

Runtime configuration

Environment is read lazily on the first authenticated tool call, so liveness (system.ping) needs no secrets. A missing slot surfaces as a structured ENV_MISSING tool error naming the exact variable. Notable variables:

| Variable | Purpose | | --- | --- | | CAPXUL_MCP_PORT | Bind port (default 8788; 0 = ephemeral). | | CAPXUL_MCP_DEV_SIGNER_SEED | Deterministic dev signer seed (--mode dev). | | CAPXUL_MCP_OAUTH_REQUIRED | 1 to require an OAuth bearer token. | | CAPXUL_MCP_OAUTH_PROOF_ISSUER_SECRET | Secret to mint proof bearer tokens. | | CAPXUL_MCP_APPROVAL_URL | Base URL of the Approval app for deploy approvals. |

Distribution

@capxul/mcp is published from the Xelmar-tech/infrastructure repo on the alpha dist-tag. The tarball is self-contained: every internal @capxul/* workspace package the server reaches (@capxul/sdk, @capxul/backend, @capxul/config, @capxul/types) is bundled into dist/main.mjs at pack time, while real npm dependencies (effect, convex, viem, zod, @modelcontextprotocol/sdk, …) stay external and are resolved from the consumer's lockfile.