MCP Server

AXON exposes its runtime MCP surface in two ways:

Hosted HTTP at https://api.axon402.com/v1/mcp — the default public path for launch users
Self-hosted stdio via axon-mcp-server — an advanced path for local development and custom deployments

For most users, the hosted HTTP endpoint is the right answer.

The runtime MCP surface is wallet-scoped and least-privilege by design. Wallet creation, vault funding, key rotation, mandate editing, and org-wide emergency stops belong on the dashboard, @axon402/cli (axon-op), or the explicit operator/manage MCP surface.

Hosted HTTP (default)

Fastest path

npx @axon402/init

That provisions your first wallet, mints a wallet-scoped runtime key, stores wallet_id + api_key in ~/.axon/config.json, and writes a hosted MCP entry into ~/.claude.json.

Manual setup

If you are not using Claude Code, or if you want to wire the entry yourself, use:

{
  "mcpServers": {
    "axon": {
      "url": "https://api.axon402.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer axon_sk_..."
      }
    }
  }
}

For Claude Code, the equivalent command is:

claude mcp add axon \
  --transport http \
  https://api.axon402.com/v1/mcp \
  --header "Authorization: Bearer axon_sk_..."

Per-IDE config examples live on IDE Setup.

Tool availability

Runtime transport split:

Hosted HTTP runtime (/v1/mcp): the current 17-tool runtime surface, including provider-search tools
Self-hosted stdio runtime: the same runtime surface over local stdio

See MCP Tools Reference for full contracts.

Recommended first session

read_spending_policy — understand the active mandate for this wallet
governed_fetch — make the first governed paid request
get_receipt — verify settlement
get_financial_status — inspect budget posture

The raw 402 signer is not a public runtime tool. New integrations should use governed_fetch.

Self-hosted stdio (advanced)

Use this path only when you are running AXON yourself.

Install

From an AXON source checkout:

npm install
npm run build

Runtime config

{
  "mcpServers": {
    "axon": {
      "command": "node",
      "args": ["/absolute/path/to/AXON/axon-402-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "BASE_RPC_URL": "https://base-mainnet.g.alchemy.com/v2/your-key",
        "MASTER_MNEMONIC": "your twelve or twenty-four word seed phrase",
        "AGENT_WALLET_ID": "wallet-id-from-bootstrap-or-workforce"
      }
    }
  }
}

Self-hosted stdio does not use HTTP bearer auth. Access control comes from local process permissions and the environment you launch it with.

Surface selection

The stdio entrypoint accepts --surface=<runtime|operator>. runtime is the default.

Flag	Effect
(omitted)	Runtime surface (default)
`--surface=runtime`	Same as omitted
`--surface=operator`	Advanced operator/manage surface over stdio

Run axon-mcp-server --help on your build to confirm accepted flags.

Demo mode

For local demo mode after npm run build, use the repo examples or generate a config block:

npm run demo:mcp-config

The example files in your local AXON checkout under examples/ are for this local stdio/demo path only. They are different from the hosted HTTP config that @axon402/init writes.

Advanced: operator / manage surface

The operator surface is explicit and separate:

Transport	Entrypoint	Credential	Tools
HTTP	`https://api.axon402.com/v1/operator/mcp`	Org-wide tenant key (`axon_sk_...`, no `wallet_id`) or static operator key	Control-plane toolset
stdio	`axon-mcp-server --surface=operator`	Local trust only; no in-process auth	Control-plane toolset

Rules:

Runtime keys are rejected on the operator entrypoint.
Runtime and operator surfaces must be mounted as separately named MCP entries.
For day-to-day operator work, prefer the dashboard or @axon402/cli.

Per-IDE operator examples live on IDE Setup.

Supported agent hosts

Host	Transport
Claude Code	Hosted HTTP or self-hosted stdio
Cursor	Hosted HTTP or self-hosted stdio
VSCode MCP extensions	Usually hosted HTTP if the extension supports streamable HTTP; otherwise self-hosted stdio
Custom MCP clients	Hosted HTTP or stdio

Getting Started

CLI

Core Concepts

Integrations

Operations

Hosted HTTP (default)

Fastest path

Manual setup

Tool availability

Recommended first session

Self-hosted stdio (advanced)

Install

Runtime config

Surface selection

Demo mode

Advanced: operator / manage surface

Supported agent hosts

​Hosted HTTP (default)

​Fastest path

​Manual setup

​Tool availability

​Recommended first session

​Self-hosted stdio (advanced)

​Install

​Runtime config

​Surface selection

​Demo mode

​Advanced: operator / manage surface

​Supported agent hosts

Hosted HTTP (default)

Fastest path

Manual setup

Tool availability

Recommended first session

Self-hosted stdio (advanced)

Install

Runtime config

Surface selection

Demo mode

Advanced: operator / manage surface

Supported agent hosts