MCP server

@capxul/mcp is a runnable Model Context Protocol server that exposes Capxul's financial operations as tools any MCP client (Claude, Cursor, other agents) can call. The package ships a CLI, not a library: the published artifact is the capxul-mcp executable. Like the SDK, the tool surface speaks money — tool results carry Money values, labels, and opaque ids, never custody internals.

Install and 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>] [--stdio]

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. (HTTP transport only.)
  --approval-url <url>  Approval app base URL. Defaults to CAPXUL_MCP_APPROVAL_URL or http://localhost:5998.
  --stdio               Serve over stdio (local spawn) instead of HTTP. Defaults to off (HTTP).
  --help                Show this help.

The server speaks MCP over Streamable HTTP at POST /mcp — a fresh, stateless server instance per request, with shared state (sessions, approvals) held in the process. Pass --stdio to serve over stdio instead, for clients that spawn the server locally.

On startup the banner prints the bound URL, the mode, whether the faucet is enabled, and the full list of registered tools. That list is computed from the live registry at boot, so it never drifts from what the server actually exposes.

Auth model

There are two independent layers:

Transport auth — OAuth bearer. An in-memory PKCE OAuth provider gates POST /mcp when CAPXUL_MCP_OAUTH_REQUIRED=1. The server publishes the standard discovery documents (/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server) and the /oauth/authorize and /oauth/token endpoints. A proof-issuer secret (CAPXUL_MCP_OAUTH_PROOF_ISSUER_SECRET) can mint bearer tokens for automated probes — and is currently required whenever OAuth is required, because external-issuer validation is not implemented yet. Stdio mode skips OAuth entirely: a local spawn is trusted IO with no bearer-token surface.

Financial auth — email OTP sessions. Signing in to Capxul happens through tools: auth.requestOtp emails a one-time code, auth.verifyOtp exchanges it for an opaque sessionToken that every session-scoped tool takes as an argument. The OTP travels only as a tool argument, and no other credential — no backend JWT, no key material — ever appears in a tool result.

The dev-mode custody gate

The --mode flag decides how money-moving operations get signed:

• --mode live (default) uses the production signer path. Full account activation needs a one-time human approval in the browser: account.ensureReady with requirement deployed returns { status: "pending", approvalUrl, approvalId } — open approvalUrl (the dedicated Approval app), complete the approval there, then poll account.deploymentStatus with the approvalId. The server itself never holds key material.
• --mode dev runs against a deterministic dev signer seed (CAPXUL_MCP_DEV_SIGNER_SEED) and a dev backend deployment, so agent journeys can be exercised headlessly, without live custody. Dev mode is also the gate for the payment tools — see tool gating below.

Runtime configuration

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

Which tools are registered

Three tiers, decided at launch:

1. Always registered — system, auth, account, identity, and payee tools.
2. Faucet — faucet.fundTestnet registers only when CAPXUL_FAUCET_ENABLED is set. Otherwise it is absent from tools/list.
3. Payments and the wider financial-ops set — payments, payment documents, orgs, payment requests, the draft workbench, and the account/org projection tools register only when the payments gate is on: --mode dev and the faucet enabled. In --mode live these tools are absent today.

A typical first session, in order: system.ping → auth.requestOtp → auth.verifyOtp (returns sessionToken) → account.ensureReady → account.balance.

Tool reference

Inputs marked ? are optional. sessionToken is always the opaque token returned by auth.verifyOtp.

System and auth

Account readiness and balance

Identity and payees

Faucet

Registered only when CAPXUL_FAUCET_ENABLED is set. Test environments only — the same guardrails as the Sandbox CLI apply: never wire the faucet into production UX.

Payments

Registered only when the payments gate is on (--mode dev + faucet enabled). Money-moving tools require the account to be ready with canTransact: true, or they fail with a wrong-state error. Amounts are Money strings such as "2 USDX". Recipients (to) are always validated — a handle, email, org handle, or Payee id, never a raw address — except payments.withdraw, whose entire purpose is an external destination.

The wider dev-mode surface

The same payments gate also registers these tool families. They mirror the SDK's org, receivables, and projection surfaces; expect them to evolve the fastest of anything on this page.

The capability constraints on the equivalent SDK surfaces apply here too — check Capability status before building a product flow on any of them.

What never crosses the wire

Tool results are leak-safe by design: they carry Money values, validated recipient labels, opaque ids, and committed document hashes. Settlement internals — transaction hashes, account addresses, raw minor units, approval token values — stay server-side. If you find one in a tool result, that is a defect worth reporting, not a feature to depend on.