> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axon402.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Hosted HTTP MCP by default, with advanced self-hosted stdio for local AXON deployments

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.

> [!NOTE]
>
> 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`](https://docs.axon402.com/docs/cli/installation) (`axon-op`), or the explicit operator/manage MCP surface.

## Hosted HTTP (default)

### Fastest path

```bash theme={null}
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:

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

For Claude Code, the equivalent command is:

```bash theme={null}
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](https://docs.axon402.com/docs/integrations/ide-setup.md).

## 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](https://docs.axon402.com/docs/api-reference/mcp-tools.md) for full contracts.

### Recommended first session

1. `read_spending_policy` — understand the active mandate for this wallet
2. `governed_fetch` — make the first governed paid request
3. `get_receipt` — verify settlement
4. `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:

```bash theme={null}
npm install
npm run build
```

### Runtime config

```json theme={null}
{
  "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"
      }
    }
  }
}
```

> [!WARNING]
>
> 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:

```bash theme={null}
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`](https://docs.axon402.com/docs/cli/installation).

Per-IDE operator examples live on [IDE Setup](https://docs.axon402.com/docs/integrations/ide-setup.md#advanced-operator-manage-surface-opt-in).

## 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.