circle-agent-stack-mcp
This server integrates with Circle's Agent Stack to manage USDC wallets, control spending policies, send USDC, and access x402-paywalled HTTP endpoints — all via MCP tool calls.
Create wallets (
circle_wallet_create): Spin up new Circle agent wallets in dev (testnet), hosted (custodial), or smart (on-chain programmable) modes.List wallets (
circle_wallet_list): Retrieve all Circle agent wallets along with their current USDC balances.Check balance & history (
circle_balance): Get the USDC balance and last 10 transactions for a specific wallet.Set spend policies (
circle_policy_set): Configure a daily USDC cap, a per-x402-call cap, and address-level allow/block lists to restrict where funds can be sent.Send USDC (
circle_transfer_usdc): Transfer USDC from a Circle wallet to any on-chain address, with an optional memo, subject to the wallet's active spend policy.Pay x402 endpoints (
circle_x402_pay): Atomically negotiate price, pay in USDC, and fetch the response from an x402-paywalled HTTP endpoint (GET or POST), with a configurable maximum price cap as a safety guard.
Provides tools for creating wallets, setting spend policies, sending USDC, and paying x402-priced endpoints through Circle's Agent Stack.
circle-agent-stack-mcp
MCP server for Circle's Agent Stack. Create wallets, set spend policies, send USDC, and pay x402-priced endpoints — all from a tool call.
npx circle-agent-stack-mcpTools
Tool | What it does |
| Create an agent wallet (dev/hosted/smart) |
| List wallets with USDC balances |
| Balance + last 10 txns for a wallet |
| Set daily cap, x402 cap, allow/block lists |
| Send USDC to an on-chain address |
| Pay an x402-priced endpoint and return its response |
Related MCP server: x402-mcp
Quickstart
You need the Circle CLI installed and authenticated:
npm install -g @circle-fin/circle-cli
circle login
export CIRCLE_API_KEY=your_key_hereClaude Desktop
{
"mcpServers": {
"circle": {
"command": "npx",
"args": ["-y", "circle-agent-stack-mcp"],
"env": {
"CIRCLE_API_KEY": "your_key_here"
}
}
}
}Claude Code
claude mcp add circle -- npx -y circle-agent-stack-mcpExample
You: Create a dev wallet called eva-treasury, set a $5 daily cap and $0.10 x402 cap,
then fetch today's BTC signal from the x402 endpoint at https://signals.example.co/btc
Claude:
→ circle_wallet_create("eva-treasury", type="dev")
{ wallet_id: "wal_abc123", address: "0x..." }
→ circle_policy_set("wal_abc123", daily_cap_usdc=5, x402_cap_usdc=0.10)
{ status: "applied" }
→ circle_x402_pay("wal_abc123", "https://signals.example.co/btc", max_price_usdc=0.10)
{ signal: "LONG", confidence: 0.72, price_paid_usdc: 0.05 }
Today's BTC signal: LONG (72% confidence). Paid $0.05.Self-hosting with x402 paywall
http-server.ts wraps the same tools behind an x402 paywall — agents pay per call in USDC rather than using an API key. Useful if you want to expose Circle tooling as a paid service.
CIRCLE_PAYOUT_ADDRESS=0x... npm run start:httpTo test the x402 flow locally, run the toy demo server in examples/x402-demo-server.mjs.
How it works
v0.1 shells out to the Circle CLI for all operations. This keeps auth handling out of this repo and avoids reimplementing the API client before the tool surface is validated. v0.2 will switch to direct HTTP via @circle-fin/circle-sdk.
Security
Your Circle API key has spend authority. Always:
Set
daily_cap_usdcbefore enabling automated paymentsStart on
type="dev"wallets, not mainnetReview the
allowlistbefore moving to productionDon't commit
CIRCLE_API_KEY
Roadmap
circle_nanopayment_stream— streaming x402 payments for per-token billingcircle_skills_list/circle_skills_call— Circle Skills marketplaceDirect HTTP API mode (v0.2) — remove CLI dependency
Multi-chain — EURC, CCTP cross-chain transfers
Related
Available Tools
6 toolscircle_balanceA
Get USDC balance and the last 10 transactions for a specific wallet.
Inputs: wallet_id (required).
circle_policy_setA
Set spend controls on a Circle wallet: daily cap, per-x402-call cap, and address allow/block lists. Always set a daily_cap before enabling automated payments.
Inputs: wallet_id (required), daily_cap_usdc (required), x402_cap_usdc (required), allowlist, +1 more.
circle_transfer_usdcA
Send USDC from a Circle agent wallet to an on-chain address. Confirm wallet policy allows the recipient address and the amount is within daily cap before calling.
Inputs: wallet_id (required), to_address (required), amount_usdc (required), memo.
circle_wallet_createA
Create a new Circle agent wallet. Returns the wallet ID and on-chain address. Start with type='dev' for testnet exploration.
Inputs: name (required), type.
circle_wallet_listA
List all Circle agent wallets and their USDC balances.
Inputs: no named parameters.
circle_x402_payA
Pay an x402-priced HTTP endpoint using USDC from a Circle wallet, then return the response body. The server negotiates price, pays atomically, and fetches the content in one step. Use max_price_usdc as a safety cap — the call fails if the endpoint quotes higher.
Inputs: wallet_id (required), endpoint_url (required), max_price_usdc (required), method, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct action: balance check, policy setting, USDC transfer, wallet creation, wallet listing, and x402 payment. There is no overlap in purpose.
All tools follow a consistent snake_case naming pattern with 'circle_' prefix and verb_noun structure (e.g., circle_balance, circle_policy_set). No style mixing.
6 tools is well-scoped for managing Circle agent wallets, covering creation, listing, balance, transfers, policy, and x402 payments. Neither too few nor too many.
Covers core wallet operations (create, list, balance, transfer, policy, x402) but lacks update or delete wallet functionality. Minor gap for full lifecycle.
Maintenance
Related MCP Connectors
MCP server for X420's pay-per-call agent services (x402, USDC on Base, paid from your own wallet).
Pay-per-use MCP tools for AI agents. USDC on Base via x402. No API keys.
Paid MCP tools behind one endpoint. Agents pay per call in USDC on Base via x402.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for AgentPay — the payment gateway for autonomous AI agents. Fund a wallet once, give your agent the key, and it discovers, provisions, and pays for tool APIs on its own. One key, every tool.112 npm1MIT
- AlicenseCqualityDmaintenanceMCP server bringing 100+ x402-paid APIs to AI agents (Claude, Cursor, MCP-aware clients). Auto-discovers tools from CDP Bazaar; handles USDC micropayments on Base.10083 npm1MIT
- FlicenseAqualityCmaintenanceMCP server for a live x402 payment gateway on Base (USDC). Lets AI agents discover, preview for free, then pay per call — with prepaid gasless payments, signed receipts, and delta delivery.7-
- AlicenseBqualityDmaintenanceAn MCP server providing 22 pay-per-call utility tools for AI agents (scrape, validate, embed, store, moderate, notify, convert, prevent loops) without accounts or API keys, using USDC payments via the x402 protocol.1753 npm1MIT