MCP servers

Two MCP stdio servers ship with agentagon[mcp]:

• agentagon-mcp: seller-side tools (register an API, list endpoints, update pricing, read revenue, export transactions, manage PATs)
• agentagon-buyer-mcp: buyer-side tools (whoami, list agents, read balance, topup URI, pay, transfer, call any paid endpoint)

Plug them into Claude Desktop, Cursor, Codex, or any MCP-aware client to drive Agentagon from inside an LLM session.

Overview

Use the MCP servers when you want to:

• Pay an x402 endpoint from inside a Claude / Cursor session without leaving the chat (call_paid_endpoint)
• Have an agent register a new service mid-session (register_api)
• Read your service’s revenue or export transactions on demand
• Drive PAT lifecycle (mint, revoke, rotate) from a chat
• Get a deposit URI prefilled for a buyer wallet (agent_topup_uri)

It’s not the right tool when you want to:

• Embed payment middleware in your service: use agentagon.seller (Python) or @agentagon/sdk/seller (Node)
• Programmatically pay from a Python script: use agentagon.buyer
• Manage services from a terminal: use agentagon-cli

Install

pip install 'agentagon[mcp]'

This adds two console scripts: agentagon-mcp and agentagon-buyer-mcp. Both are stdio servers; you point your MCP client at the binary path.

Quickstart

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentagon-buyer": {
      "command": "agentagon-buyer-mcp",
      "env": {
        "AGENTAGON_PAT": "ag_pat_..."
      }
    },
    "agentagon": {
      "command": "agentagon-mcp",
      "env": {
        "AGENTAGON_PAT": "ag_pat_..."
      }
    }
  }
}

Restart Claude Desktop. Both servers register their tools automatically.

Cursor

{
  "mcp.servers": {
    "agentagon-buyer": {
      "command": "agentagon-buyer-mcp",
      "env": { "AGENTAGON_PAT": "ag_pat_..." }
    }
  }
}

Same shape; Cursor’s settings UI also has a friendly form. Use whichever you prefer.

Validate setup

In your MCP client, ask “what tools do you have for Agentagon?” The buyer server should list whoami, agent_list, agent_balance, agent_topup_uri, pay, transfer, call_paid_endpoint. The seller server lists register_api, list_endpoints, update_pricing, get_revenue, export_transactions, list_keys, revoke_key, rotate_key.

If tools don’t appear, restart the client and check the client’s MCP logs for stdio errors.

Tool reference: agentagon-buyer-mcp

Buyer-side tools. Auth comes from AGENTAGON_PAT env, or falls back to ~/.config/agentagon/credentials.json (the file written by agentagon login).

whoami

whoami() -> { auth_type, scope_type, scope_id, daily_cap_usd }

Returns the active token’s scope. Use as a sanity check on first contact: which agent are we, what are we allowed to spend.

agent_list

agent_list() -> [ { agent_id, label, address, chain }, ... ]

Lists every agent the active PAT can see (its own, plus any that share scope).

agent_balance

agent_balance(sub_wallet_id) -> { balance_raw, balance_pending_raw, stale, updated_at }

Live balance for a sub-wallet. Treasury falls back to its cache when the on-chain RPC is unreachable; stale=true flags this. Surface the staleness in your reply.

Requires either AGENTAGON_TREASURY_KEY env or a Treasury-scoped PAT in AGENTAGON_PAT.

agent_topup_uri

agent_topup_uri(sub_wallet_id, amount_usd?) -> { uri, chain }

Builds an EIP-681 payment URI prefilled with the agent’s address. Buyers can hand it to a wallet (Coinbase Wallet, Rainbow, etc.) and confirm in one tap. For Solana sub-wallets the URI is empty; the chain is in the response so the caller knows.

pay

pay(sub_wallet_id, to, amount_usd, capability?) -> SignedPayment

Sign an x402 EIP-3009 TransferWithAuthorization. Returns the signed authorization + signature; the caller (the LLM, with help) hands it to a facilitator, or feeds it back into call_paid_endpoint.

transfer

transfer(sub_wallet_id, to, amount_usd) -> SignedTransfer

Sign an external EIP-3009 transfer (no x402 framing). For wallet-to-wallet flows.

call_paid_endpoint

call_paid_endpoint(url, method?, body?, headers?, max_price_usd?) -> { status, content, spent_usd, tx_hash }

The end-to-end probe-to-response orchestrator. Runs the x402 dance: probe the URL, if 402 then pick an accept, sign with the active agent’s wallet, retry. Returns the seller’s response plus what was paid.

This is the single tool that makes “pay any x402 endpoint from chat” work. Most LLM-driven flows only need this one tool plus whoami for context.

Tool reference: agentagon-mcp

Seller-side tools. Auth comes from AGENTAGON_PAT (service-scoped PAT).

register_api

register_api(name, openapi_url?, capabilities?) -> { seller_id, pat }

Registers a new service. Equivalent to agentagon service init in the CLI. Returns the new seller_id and a service-scoped PAT.

list_endpoints

list_endpoints(seller_id?) -> [ { id, slug, path, price, ... }, ... ]

Lists every endpoint registered for the service. seller_id defaults to the active service.

update_pricing

update_pricing(endpoint_id, price) -> { ok }

Update the price for an endpoint. Mirrors agentagon endpoints price.

get_revenue

get_revenue(seller_id?, period?) -> { total_usd, transactions, by_endpoint }

Revenue summary. Defaults to the active service.

export_transactions

export_transactions(seller_id?, format?) -> string  # JSON or CSV

Export the ledger. format is json or csv.

list_keys / revoke_key / rotate_key

PAT management for the active service. Lists are metadata-only (no raw values); revoke needs explicit confirmation; rotate produces a new PAT and invalidates the old one.

Cookbook

Onboarding flow inside Claude Desktop

A canonical first-run script the LLM can guide users through:

1. whoami: check who we are. If auth_type == "missing", prompt for AGENTAGON_PAT.
2. agent_list: confirm at least one agent is registered.
3. agent_balance(sub_wallet_id): read the active wallet balance.
4. If the balance is too low for typical paid calls, agent_topup_uri(sub_wallet_id, "5.00") and surface the URI to the user.
5. Once funded, call_paid_endpoint(url) to actually buy something.

The agentagon-buyer-mcp server’s instructions field embeds this flow so MCP clients can reproduce it without prompting from the LLM.

Calling a paid endpoint with a body

call_paid_endpoint(
  url="https://api.example.com/v1/translate",
  method="POST",
  body={"text": "hello", "target": "ja"},
  headers={"Content-Type": "application/json"},
  max_price_usd="0.05"
)

The server runs the dance and returns {status, content, spent_usd, tx_hash}. The LLM can then quote the response back to the user with the cost.

Branching on a recovery from pay

pay(sub_wallet_id, to, amount_usd) -> SignedPayment | { error: { recovery: { kind, ... } } }

If the platform refuses (daily cap, insufficient balance, capability cap), the response is an error object with a recovery block. The LLM can ask the user “raise the cap?” and re-invoke with a higher cap, or surface the deposit URI from recovery.deposit_url.

Auth fallback chain

The buyer server resolves the bearer in this order:

1. AGENTAGON_PAT env var
2. AGENTAGON_TREASURY_KEY env var (for Treasury calls)
3. ~/.config/agentagon/credentials.json (written by agentagon login)
4. The active agent’s PAT in ~/.agentagon/agents/<id>.json

The first one set wins. If none is set, whoami returns an error explaining what to do.

Driving PAT rotation from a chat

list_keys                          # see what's there
rotate_key(pat_token_id="pt_xxx")  # mint a new one, invalidate old

The new PAT comes back in the response once. The chat client should redact it from logs; the platform doesn’t keep a recoverable copy.

Errors

MCP tools return JSON-RPC errors for transport-level failures and tool-result objects with isError: true for tool-level failures. Both surface a structured payload your client can branch on.

Catalog (buyer-mcp)

Catalog (seller-mcp)

The MCP servers never crash on bad input. Unknown tools, malformed args, and HTTP errors all return structured responses; the stdio frame stays alive so the session can recover.

Troubleshooting

Tools don’t appear in Claude Desktop

Check the MCP server log: Claude Desktop > Settings > Developer > MCP Logs. Common causes:

• The binary isn’t on PATH: use the absolute path (which agentagon-buyer-mcp)
• agentagon[mcp] isn’t installed: pip install 'agentagon[mcp]'
• The env var didn’t propagate: print ${AGENTAGON_PAT:-not-set} from a shell first to confirm

missing_bearer even with env var set

Claude Desktop’s env config only affects the spawned subprocess. If you set AGENTAGON_PAT in your shell profile, it’s not visible to the MCP server. Set it in the JSON config’s env block, not in .zshrc.

call_paid_endpoint returns “no compatible accept”

The seller’s 402 had no scheme/network compatible with the active agent. Check the seller’s accepts[] from the error payload’s recovery.offered_schemes. Add a Solana wallet (agentagon agent wallets add --chain solana) if the seller is Solana-only.

Stale balance won’t refresh

agent_balance calls Treasury, which falls back to its cache when the upstream RPC is unreachable. The flag stays true until the next successful read. Ask the LLM to wait 30 seconds and try again, or check the seller’s status page.

Auth migration: I’m using a master key

Master keys (ag_live_sk_*) were hard-cut on 2026-04-27. The MCP server detects and refuses them. Run:

agentagon init                                # bootstrap a session
agentagon service pat create --label mcp      # mint a PAT for the MCP

Then update the AGENTAGON_PAT env in your MCP client config.

How does this compare to the CLI?

The MCP servers are essentially a JSON-RPC wrapper over the same operations the CLI exposes. Use the CLI for terminal use; use MCP when an LLM is driving. The seller-mcp tools map almost one-to-one to agentagon service * and agentagon endpoints *. The buyer-mcp tools map to agentagon buy plus the agent / wallet helpers.