MCP Tools Overview

The AXON MCP toolset is split across two explicit surfaces. The runtime surface is the default worker-agent path. The operator/manage surface is an advanced control-plane path for trusted admin automation. The runtime surface exposes the tools a worker agent needs to use a prepared wallet safely: governed spend, policy and budget reads, approval loops, receipts, and outcome reporting. Wallet lifecycle, treasury, key rotation, mandate edits, and org-wide emergency actions are control-plane responsibilities and live in the dashboard and @axon402/cli (axon-op).

If you are wiring an IDE or agent host, start with MCP Server for the runtime surface and IDE Setup for the operator/manage surface. Teach governed_fetch first; it is the default runtime spend path and the primary story for new integrations.

Runtime Configuration

{
  "mcpServers": {
    "axon": {
      "command": "node",
      "args": ["<repo-root>/axon-402-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "...",
        "SUPABASE_SERVICE_KEY": "...",
        "BASE_RPC_URL": "...",
        "MASTER_MNEMONIC": "...",
        "AGENT_WALLET_ID": "..."
      }
    }
  }
}

Transport split:

stdio runtime (axon-mcp-server, default surface) exposes the same current 17-tool runtime surface as HTTP
HTTP runtime (/v1/mcp) exposes that runtime surface over Streamable HTTP

HTTP runtime nuance:

wallet-bound tenant keys are the canonical credential for /v1/mcp
org-wide tenant keys with no wallet binding receive a JSON-RPC WALLET_BINDING_REQUIRED error
static operator-key fallback on /v1/mcp is demo-only; live worker agents should use wallet-bound tenant keys

Runtime Tool Categories

Default spend path

Tool	Purpose
`governed_fetch`	Primary runtime story — AXON evaluates policy, signs, settles, and retries the x402 call
`get_receipt`	Settlement receipt lookup after a successful spend

Runtime context

Tool	Purpose
`read_spending_policy`	Retrieve the active mandate for this wallet
`get_financial_status`	Budget traffic light
`get_balance`	Wallet balance check
`verify_transaction`	On-chain transaction verification helper

Approvals and budget requests

Tool	Purpose
`check_approval_status`	Poll approval state and surface `approval_token` when approved
`consume_approval_token`	Read-only token fetch for an approved request
`wait_for_approval_resolution`	Long-poll until an approval becomes approved, denied, or expired
`request_budget_increase`	Ask the operator for more budget

Forensics and outcomes

Tool	Purpose
`explain_denial`	Decision forensics
`list_decisions`	Decision history for this wallet
`report_outcome`	Report whether the paid result was fulfilled

Provider-search tools

These tools are part of the runtime surface and are available on stdio runtime, /v1/mcp, and /v1/wallets/:wallet_id/mcp.

Tool	Purpose
`search_x402_services`	Search x402 provider offers using the canonical `services` response field
`inspect_x402_offer`	Inspect a discovered offer
`quote_x402_offer`	Fetch a fresh quote for a discovered offer
`test_buy_x402_offer`	Run a buyer-journey test buy through the caller’s wallet binding

pay_402_challenge is no longer runtime-exposed. governed_fetch is the supported runtime path for paying a 402 challenge; the raw signer is still used internally for gated retry/test-buy flows after AXON policy checks pass.

Operator / manage actions

The following actions are control-plane responsibilities. They are available to operators via the dashboard, @axon402/cli (axon-op), or the explicit operator/manage MCP surface — not through the runtime MCP surface:

Wallet lifecycle: list_wallets, create_wallet, get_wallet_details
Treasury and emergency controls: fund_pocket, emergency_stop
Offer operations: list_offers, get_offer, create_offer, publish_offer, unpublish_offer, configure_origin, test_buy_offer, pause_offer, resume_offer, archive_offer
Org and key introspection: whoami, get_organization, list_api_keys, inspect_api_key, list_transactions, get_earnings, get_ledger, list_mandates, update_mandate

Error Contract

MCP tools return structured errors with isError: true:

{
  "code": "APPROVAL_REQUIRED",
  "message": "Payment escalated for human approval.",
  "recoverable": true,
  "suggested_action": "Approve in dashboard, then call check_approval_status to retrieve approval_token, then retry governed_fetch with approval_token.",
  "details": { "decision_id": "..." }
}

See Error Codes for the complete reference.

Overview

Onboarding

Core Spend

Approvals

Organizations

Treasury

Providers

Discovery

Workers & Observability

MCP Tools

Reference

MCP Tools Overview

Runtime Configuration

Runtime Tool Categories

Default spend path

Runtime context

Approvals and budget requests

Forensics and outcomes

Provider-search tools

Operator / manage actions

Error Contract

​Runtime Configuration

​Runtime Tool Categories

​Default spend path

​Runtime context

​Approvals and budget requests

​Forensics and outcomes

​Provider-search tools

​Operator / manage actions

​Error Contract

Runtime Configuration

Runtime Tool Categories

Default spend path

Runtime context

Approvals and budget requests

Forensics and outcomes

Provider-search tools

Operator / manage actions

Error Contract