MCP server

Run the Capxul OAuth resource server and use its Person, Account, and Organization tools.

@capxul/mcp is the published Capxul Model Context Protocol server. It is a stateless OAuth resource server in front of @capxul/sdk. The package ships the capxul-mcp executable. It serves protocol revision 2026-07-28. HTTP also serves the stateless 2025-06-18 handshake used by Codex.

Run the server

npx @capxul/mcp serve

HTTP mode serves Streamable HTTP at POST /mcp. It binds 127.0.0.1:8788 by default. Stdio mode is also available:

CAPXUL_MCP_ACCESS_TOKEN="<access-token>" capxul-mcp serve --stdio

The server reads the bearer from the HTTP authorization header or the stdio environment. No tool accepts a credential as an argument.

Connect Codex

codex mcp add capxul --url http://127.0.0.1:8788/mcp
codex mcp login capxul

Codex reads the protected-resource document, discovers the Capxul authorization server, and opens the Capxul login and consent pages. The hosted staging endpoint is https://capxul-mcp-production.up.railway.app/mcp. Its canonical staging DNS name is still pending.

Current tools

Tool	Required scope	Result
`system.ping`	public	Echo an optional value.
`system.health`	public	Round-trip a nonce through the configured backend.
`onboarding.completePerson`	`account:write`	Claim a unique username, complete the Profile, and ready the personal Account.
`onboarding.completeOrganization`	`org:manage`	Claim the personal Account, then create or resume an Organization.
`me.get`	`account:read`	Read the signed-in Person profile.
`account.status`	`account:read`	Read the Account setup lifecycle.
`account.balance`	`account:read`	Read exact positions and nullable single-asset amounts.
`org.list`	`org:manage`	List accessible Organizations.
`org.roles`	`org:manage`	List active Organization role labels.
`org.members`	`org:manage`	Read member lifecycle states.

Call onboarding.completePerson for every new Person. The input is:

{
  "displayName": "Ada Lovelace",
  "country": "GH",
  "username": "ada_lovelace"
}

The username is mandatory. It must contain 3–30 lowercase letters, numbers, or underscores. The backend rejects reserved or already-owned usernames. Account setup does not start until the Profile write accepts the username.

The result contains the stored Profile and a ready Account lifecycle. The canTransact value states whether the current client requirement supports signed money operations.

Call onboarding.completeOrganization only after Person onboarding. Its input contains name, handle, and an ISO country. bio and size are optional. The handle contains 3–32 lowercase letters, numbers, or hyphens. Organization onboarding needs a signer. The hosted live server has no signer and fails closed. The explicit development mode supplies a deterministic proof signer.

When PostHog MCP Analytics is configured, every tool requires context and accepts conversation_id. The server converts free-form context to a safe journey category before capture. It does not capture tool arguments, tool responses, email, raw errors, addresses, or exception events. It uses the pseudonymous Capxul auth user ID as distinct_id.

Invitation authoring and digest-bound acceptance use the SDK or CLI. MCP exposes Organization and member reads but does not author or activate invitations.

Evidence boundary

Hermetic tests use a real MCP HTTP server, a fake token exchange, and a fake SDK client. The staging proof in issue #1812 proves browser OAuth, onboarding.completePerson, a ready Account, OAuth scope step-up, and the Account tools. A second fresh Person also received the typed username conflict. A signed staging run created a ready Organization and confirmed the Base Sepolia transaction. The hosted Codex and PostHog Analytics proof is separate because the hosted live server does not hold a signer.

The historical three-phase staging harness, recorded before the MCP invitation tools were retired, created a founder and staff Person, invited the staff Person, accepted the invitation, assigned the role through the existing Permission execution, and observed the member become active. It does not prove the current MCP tool surface. The verified Base Sepolia assignment transaction is 0x7e717946…48766d.

The Openfort browser spike also passed in #1812. A real iframe signed a known digest, and a current browser SDK payment settled on Base Sepolia. The MCP does not expose a signing or money tool yet.

Current limits

Payroll, payment, prompt, and resource surfaces are not registered yet.
Streaming payroll has no current SDK contract and is not in the MCP scope.
Tool results omit signatures, raw units, calldata, and provider credentials.