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

# IDE Setup

> Hosted HTTP MCP by default, with advanced self-hosted stdio and operator/manage options

AXON exposes two MCP surfaces. For almost every launch user, the right starting point is the **hosted runtime MCP endpoint** at `https://api.axon402.com/v1/mcp`. `@axon402/init` is the fastest way to wire that into Claude Code. Self-hosted stdio is still available, but it is an advanced path for local development and custom deployments.

> [!NOTE]
>
> **One key = one surface.** A runtime (wallet-scoped) key belongs on the runtime entry. An operator (org-wide) key belongs on the operator entry. Never combine the two surfaces under one MCP server name, and never hand an operator key to a worker agent. `GET /v1/me` returns the authoritative `surface` field for any tenant key.

## Which surface do I need?

| Goal | Surface | Key shape | Default? |
| :- | :- | :- | :- |
| A worker agent spends through a prepared wallet | Runtime | Wallet-scoped runtime key (`axon_sk_...` with `wallet_id` bound) | Yes |
| IDE-native control-plane automation (wallets, treasury, offers, mandates, org introspection) | Operator / manage | Org-wide operator key (`axon_sk_...`, no `wallet_id`) | No. Advanced. |
| Day-to-day operator work from the terminal | Not MCP | Use [`@axon402/cli`](https://docs.axon402.com/docs/cli/installation) (`axon-op`) | — |

If you are not sure, you want the runtime surface.

## Runtime surface (default)

The hosted runtime endpoint is:

```text theme={null}
https://api.axon402.com/v1/mcp
```

This is the public path for Claude Code, Cursor, and any MCP client that supports streamable HTTP. It exposes the current 17-tool wallet-scoped runtime surface, including provider-search tools: `search_x402_services`, `inspect_x402_offer`, `quote_x402_offer`, and `test_buy_x402_offer`.

### Bootstrap once

```bash theme={null}
npx @axon402/init
```

That command:

* creates your first wallet
* mints a wallet-scoped runtime key
* stores `wallet_id` + `api_key` in `~/.axon/config.json`
* merges a hosted HTTP `axon` MCP entry into `~/.claude.json`

If you are not using Claude Code, still run `@axon402/init` first. The generated `wallet_id` and `api_key` are what you need for Cursor, VSCode, OpenClaw, and direct REST integrations.

### Claude Code

`@axon402/init` already writes the hosted runtime entry into `~/.claude.json`. If you need to add it manually instead:

```bash theme={null}
claude mcp add axon \
  --transport http \
  https://api.axon402.com/v1/mcp \
  --header "Authorization: Bearer axon_sk_..."
```

Equivalent JSON:

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

### Cursor

Cursor reads `.cursor/mcp.json` in the workspace root or `~/.cursor/mcp.json` globally. Use the same hosted HTTP shape:

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

### VSCode

Many MCP extensions accept the same `url` + `headers` payload under their server map. If yours supports streamable HTTP MCP, configure the runtime entry with the hosted endpoint and a wallet-scoped runtime key:

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

### Generic MCP clients

If the client supports streamable HTTP MCP, point it at `https://api.axon402.com/v1/mcp` and send:

```http theme={null}
Authorization: Bearer axon_sk_...
```

> [!NOTE]
>
> OpenClaw and direct REST integrations are **not** MCP. They should reuse the same runtime key, but they also need the `wallet_id` from `~/.axon/config.json` because their REST calls do not auto-resolve it the way hosted MCP does.

### Verifying the runtime surface

* Hosted HTTP runtime should list **17 tools**, including the provider-search tools.
* Self-hosted stdio runtime should list the same runtime surface.
* If you see `create_wallet`, `list_wallets`, `fund_pocket`, or other control-plane tools on the runtime entry, that is a surface leak and should be reported as a bug.

## Advanced: self-hosted stdio runtime

Use this only when you are running AXON yourself or doing local development. Public launch users do not need this path.

From an AXON source checkout:

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

Example MCP entry:

```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"
      }
    }
  }
}
```

Notes:

* Omitting `--surface` is the same as `--surface=runtime`.
* Self-hosted stdio does not use HTTP bearer auth; trust comes from local process access and environment control.
* `AGENT_WALLET_ID` pins the runtime wallet for stdio sessions.
* For local demo mode, use `npm run demo:mcp-config` from an AXON source checkout, or copy the `examples/claude-code-mcp.json` template from your local clone.

## Advanced: operator / manage surface (opt-in)

> [!WARNING]
>
> Do not use this surface for worker agents. The operator surface is for trusted developer or admin automation only. For normal operator work, use the AXON dashboard or [`@axon402/cli`](https://docs.axon402.com/docs/cli/installation) (`axon-op`).

The hosted operator endpoint is:

```text theme={null}
https://api.axon402.com/v1/operator/mcp
```

It requires an **org-wide** operator key. Wallet-scoped runtime keys are rejected here.

### Claude Code

```bash theme={null}
claude mcp add axon-operator \
  --transport http \
  https://api.axon402.com/v1/operator/mcp \
  --header "Authorization: Bearer axon_sk_ORG_WIDE_OPERATOR_KEY"
```

Equivalent JSON:

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

### Cursor / VSCode

Mount the same two named entries in your MCP config:

* `axon` -> `https://api.axon402.com/v1/mcp` with a wallet-scoped runtime key
* `axon-operator` -> `https://api.axon402.com/v1/operator/mcp` with an org-wide operator key

Never reuse the runtime key on the operator entry, and never replace the runtime entry with the operator one.

### Self-hosted stdio operator

If you run AXON locally and need operator tools over stdio:

```bash theme={null}
node /absolute/path/to/AXON/axon-402-mcp/dist/index.js --surface=operator
```

This transport has no in-process auth. Whoever can launch it controls the operator toolset.

### Verifying the operator surface

The operator entry should expose control-plane tools only: wallet lifecycle, treasury movement, offer management, API key and mandate operations, approvals, ledger/earnings views, and organization introspection. If you see `governed_fetch` on the operator entry, that is a surface leak.

## Credential model recap

* **Runtime key**: wallet-scoped tenant key. Belongs on `https://api.axon402.com/v1/mcp` only.
* **Operator key**: org-wide tenant key. Belongs on `https://api.axon402.com/v1/operator/mcp` or `axon-op`.
* **One key, one surface**: a single key does not carry both runtime and operator privileges.

## See also

* [MCP Server integration](https://docs.axon402.com/docs/integrations/mcp-server.md) — the runtime-plane surface overview
* [OpenClaw Plugin](https://docs.axon402.com/docs/integrations/openclaw-plugin.md) — a runtime-only plugin integration
* [CLI installation](https://docs.axon402.com/docs/cli/installation.md) — `@axon402/init` (runtime bootstrap) and `@axon402/cli` (operator CLI)
* [REST API Integration](https://docs.axon402.com/docs/integrations/rest-api.md) — direct HTTP integration
* [Two-Surface Migration](https://docs.axon402.com/docs/integrations/two-surface-migration.md) — splitting older mixed setups


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