IDE Setup

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.

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` (`axon-op`)	—

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

Runtime surface (default)

The hosted runtime endpoint is:

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

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:

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

Equivalent JSON:

{
  "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:

{
  "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:

{
  "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:

Authorization: Bearer axon_sk_...

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:

npm install
npm run build

Example MCP entry:

{
  "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)

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 (axon-op).

The hosted operator endpoint is:

https://api.axon402.com/v1/operator/mcp

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

Claude Code

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:

{
  "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:

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.

Getting Started

CLI

Core Concepts

Integrations

Operations

Which surface do I need?

Runtime surface (default)

Bootstrap once

Claude Code

Cursor

VSCode

Generic MCP clients

Verifying the runtime surface

Advanced: self-hosted stdio runtime

Advanced: operator / manage surface (opt-in)

Claude Code

Cursor / VSCode

Self-hosted stdio operator

Verifying the operator surface

Credential model recap

See also

​Which surface do I need?

​Runtime surface (default)

​Bootstrap once

​Claude Code

​Cursor

​VSCode

​Generic MCP clients

​Verifying the runtime surface

​Advanced: self-hosted stdio runtime

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

​Claude Code

​Cursor / VSCode

​Self-hosted stdio operator

​Verifying the operator surface

​Credential model recap

​See also

Which surface do I need?

Runtime surface (default)

Bootstrap once

Claude Code

Cursor

VSCode

Generic MCP clients

Verifying the runtime surface

Advanced: self-hosted stdio runtime

Advanced: operator / manage surface (opt-in)

Claude Code

Cursor / VSCode

Self-hosted stdio operator

Verifying the operator surface

Credential model recap

See also