APN MCP server

Agent Payment Node (APN) includes a local stdio MCP server, so an AI agent can prepare and track payments through MCP tools. This page explains how to start it, which tools it exposes, and why every approval command goes back to a human in a terminal. Here APN means the open-source payment runtime for AI agents, not an Access Point Name and not the AWS Partner Network.

Updated

What is the APN MCP server?

Agent Payment Node (APN) is an open-source, local-first payment runtime for AI agents. An agent drives it through the apn CLI or through a local stdio MCP server. A human owner sets the spending limits and approves direct transfers in a foreground terminal.

The MCP server is the same runtime behind a different door. Its tools are projected from the same command catalog as the CLI and run the same code. An agent that calls an MCP tool gets the same checks, the same policy limits and the same durable operation records as an agent that runs the CLI command.

The server speaks stdio and runs on your own machine. Remote MCP is not part of the repository: the README lists hub, contracts, remote MCP and Stellar as outside it. APN runs on Apple Silicon macOS with Node 24 (see install).

How do I start it: apn mcp config and apn mcp serve

Two commands cover the whole lifecycle. apn mcp config prints the launch descriptor. apn mcp serve runs the stdio server.

apn mcp config
apn mcp serve

Both commands appear in the generated command catalog of the README. You normally do not run apn mcp serve by hand: your MCP client starts it as a child process and talks to it over stdin and stdout.

How do I connect an MCP client to APN?

The repository documents one connection step: run apn mcp config and use the launch descriptor it prints to register the server in your MCP client. The repository does not document per-client setup, so this site does not show a configuration file for any specific client. Check your client's own documentation for where a stdio server is registered.

  1. Install APN with brew install nuanu-ai/tap/apn (see install).
  2. Run apn mcp config and read the launch descriptor it prints.
  3. Register that descriptor in your MCP client as a local stdio server.
  4. Ask the agent to call a read-only tool first, such as the wallet balance tool, before any money command.

Before money can move, the owner still has to set limits in a terminal. Follow the quickstart for the first wallet and policy.

Which tools does the APN MCP server expose?

Tool names follow the CLI command path with underscores. The repository shows names such as apn_wallet_balance, apn_pay_transfer_prepare_asset, apn_operation_status, apn_operation_resume, apn_receipt_get, apn_bridge_routes, apn_gasless_usdt_prepare and apn_x402_permit2_status.

Two things hold for every tool:

  • The tool validates its arguments exactly as the CLI does, because it runs the same code.
  • A command prints one apn.cli.v1 JSON envelope with ok, error, operation, receipt and next_actions, and next_actions names the next command to run or the option to fix.

The full tool list is not copied here. The machine source of truth for the installed version is apn help --json, which prints one apn.command-manifest.v2 JSON object. A matching version number does not prove that an installed artifact contains a given source change, so check apn --version, the release provenance and apn help --json together.

Some families have fewer MCP tools than CLI commands. For example, Relay is not exposed as MCP tools, and the MetaMask native transfer is CLI only. The foreground Permit2 lane has one MCP tool, apn_x402_permit2_status, for reading an operation; x402 permit2 approve and observe have no MCP tools of their own.

Why does MCP never approve a payment?

Foreground approval needs stdin and stderr attached to real TTYs and an exact operation-bound code within 60 seconds. An MCP server has no such terminal, so it cannot run an approval. The README states this as the rule "MCP never approves". The unattended x402 lanes described below are the only payments that run over MCP without a typed code, and they stay inside caps the owner set in the foreground.

Commands that need a human are therefore not separate MCP tools. Approve, execute, abandon, wallet connect and allowlist activate all fall in this group. One tool, apn_foreground_handoff, replaces them:

  • It validates the arguments exactly as the CLI does.
  • It returns the exact command for the human to run in a terminal.
  • It reads and writes nothing.
  • For allowlist policy activate or revoke, it decides nothing and returns APN_FOREGROUND_APPROVAL_REQUIRED with the exact cli_handoff command.

wallet policy set runs over MCP only for a pure decrease. A new policy or an increase returns the handoff. Lowering a limit needs no terminal; raising one does.

The handoff covers every foreground command of a family that MCP exposes, including gasless usdt execute and x402 permit2 approve. See security for the full approval model.

Which APN commands are CLI-only and have no MCP handoff?

Ten foreground commands have no handoff. MCP exposes no prepare, quote or status tool for their families, so an agent never holds their inputs or operations. These families are CLI only:

  • stargate native execute
  • stargate token execute
  • stargate token cleanup
  • relay execute
  • relay retire
  • wallet metamask native-transfer
  • circle approval execute
  • circle source submit
  • sei funding approve
  • mega funding approve

The human owner runs these directly in a terminal. See bridges for the bridge families and wallets for the MetaMask native transfer.

Can an agent pay x402 sellers over MCP?

Yes, for the lanes the repository marks as unattended. Standard EVM x402 (x402 inspect, x402 fetch prepare and approve) is unattended in both the CLI and MCP, under the profile x402 policy for the exact chain and token. x402 solana pay also runs unattended over CLI or MCP for a mint the owner's allowlist row admits.

The foreground Permit2 lane and the ERC-20 transfer-proof merchant lane are CLI commands with foreground approval. Details are on the x402 page. The owner policy has to exist first: the agent never creates or raises its own limits.

What happens when an MCP call is interrupted?

Payments are durable operations with idempotency keys. If the agent loses the response, it can read the operation with apn_operation_status and continue with apn_operation_resume. Resume performs only the next legal transition. A lost outcome is reported as ambiguous and is never resent blindly. The recovery page explains the states.

For how MCP, x402 and the Agent Payments Protocol relate to each other, read x402, AP2 and APN.

Questions

What does apn mcp serve do?

It runs APN's local stdio MCP server. Its tools are projected from the same command catalog as the CLI and run the same code.

What does apn mcp config do?

It prints the launch descriptor for the MCP server, which you use to register APN in an MCP client.

Can an AI agent approve its own payment through APN MCP?

No. Approval needs a human at a foreground terminal who types an operation-bound code, and MCP returns the exact command through apn_foreground_handoff instead. Unattended x402 purchases need no approval step, but they run only inside the caps the owner set in the foreground.

Is there a remote or hosted APN MCP server?

Not in the repository. The README lists remote MCP as outside it. APN's MCP server is local and uses stdio.

Which operating systems does the APN MCP server support?

APN runs on Apple Silicon macOS with Node 24. Linux and Windows are unsupported in the platform support matrix.

Sources
  1. README: How APN works (MCP never approves)
  2. README: Install and Node requirement
  3. README: Custody and threat model (foreground approval)
  4. README: Proof boundary (remote MCP outside the repository)
  5. docs/allowlist-policy.md: activate and revoke are not MCP tools
  6. docs/x402-any-seller.md: admission lanes
  7. docs/x402-non-usdc.md: Permit2 MCP column
  8. docs/relay.md and docs/platform-support.md