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

> Runtime-plane MCP tools for AI agents

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`).

> [!NOTE]
>
> If you are wiring an IDE or agent host, start with [MCP Server](https://docs.axon402.com/docs/integrations/mcp-server.md) for the runtime surface and [IDE Setup](https://docs.axon402.com/docs/integrations/ide-setup.md) 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

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

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

```json theme={null}
{
  "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](https://docs.axon402.com/docs/api-reference/error-codes.md) for the complete reference.


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