Circle Agent Stack MCP server
✓ VerifiedEnables AI agents to manage USDC wallets, set spend policies, execute transfers, and process x402 nanopayments.
Also known as kinance/circle-agent-stack-mcp
- Stars
- 1
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Jun 4, 2026
- License
- MIT
What is Circle Agent Stack MCP?
Circle Agent Stack enables AI agents to manage USDC wallets, set spend policies, execute transfers, and process x402 nanopayments. It exposes 6 tools, such as circle_wallet_create, circle_wallet_list, circle_balance.
Summary generated from the project's README
About Circle Agent Stack MCP server
Managing USDC wallets and executing nanopayments through AI agents is possible with this MCP server. It allows developers to integrate financial capabilities directly into agentic workflows, enabling automated tasks like creating dev or smart wallets, checking balances, and sending USDC to on-chain addresses. The server functions by shelling out to the Circle CLI, which requires the Circle CLI to be installed and authenticated on your local machine with a valid API key.
Users can implement strict financial controls by using the circle_policy_set tool to define daily caps, x402 caps, and allow or block lists. This ensures that autonomous agents operate within predefined budget limits. The server also supports the x402 protocol, allowing agents to pay for specific endpoints using the circle_x402_pay tool. This setup is ideal for developers building autonomous agents that need to interact with paid APIs or manage treasury funds via USDC.
What you can do with it
- 1Micro-payments for API accessPay for specific data endpoints using x402 nanopayments directly through a tool call.
- 2Wallet monitoring and auditingRetrieve current USDC balances along with the ten most recent transactions for a specific wallet.
- 3On-chain USDC transfersSend USDC funds to a designated on-chain address using the agent's wallet.
Written from the project's README. Every use case is checked against a quote from it.
How to install Circle Agent Stack MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Circle Agent Stack MCP in Claude Code
$ claude mcp add --env 'CIRCLE_API_KEY=<YOUR_CIRCLE_API_KEY>' circle-agent-stack-mcp -- npx -y circle-agent-stack-mcpInstall Circle Agent Stack MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"circle-agent-stack-mcp": {
"command": "npx",
"args": [
"-y",
"circle-agent-stack-mcp"
],
"env": {
"CIRCLE_API_KEY": "<YOUR_CIRCLE_API_KEY>"
}
}
}
}Install Circle Agent Stack MCP in VS Code
.vscode/mcp.json
{
"servers": {
"circle-agent-stack-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"circle-agent-stack-mcp"
],
"env": {
"CIRCLE_API_KEY": "<YOUR_CIRCLE_API_KEY>"
}
}
}
}Install Circle Agent Stack MCP in VS Code CLI
$ code --add-mcp '{"name":"circle-agent-stack-mcp","type":"stdio","command":"npx","args":["-y","circle-agent-stack-mcp"],"env":{"CIRCLE_API_KEY":"<YOUR_CIRCLE_API_KEY>"}}'Install Circle Agent Stack MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"circle-agent-stack-mcp": {
"command": "npx",
"args": [
"-y",
"circle-agent-stack-mcp"
],
"env": {
"CIRCLE_API_KEY": "<YOUR_CIRCLE_API_KEY>"
}
}
}
}Install Circle Agent Stack MCP in Codex
$ codex mcp add circle-agent-stack-mcp --env 'CIRCLE_API_KEY=<YOUR_CIRCLE_API_KEY>' -- npx -y circle-agent-stack-mcpInstall Circle Agent Stack MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.circle-agent-stack-mcp] command = "npx" args = ["-y", "circle-agent-stack-mcp"] [mcp_servers.circle-agent-stack-mcp.env] CIRCLE_API_KEY = "<YOUR_CIRCLE_API_KEY>"
Install Circle Agent Stack MCP in Gemini CLI
$ gemini mcp add -s user -e 'CIRCLE_API_KEY=<YOUR_CIRCLE_API_KEY>' circle-agent-stack-mcp npx -- -y circle-agent-stack-mcpInstall Circle Agent Stack MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"circle-agent-stack-mcp": {
"command": "npx",
"args": [
"-y",
"circle-agent-stack-mcp"
],
"env": {
"CIRCLE_API_KEY": "<YOUR_CIRCLE_API_KEY>"
}
}
}
}Circle Agent Stack MCP tools 6
Detected from the READMEcircle_wallet_createcircle_wallet_listcircle_balancecircle_policy_setcircle_transfer_usdccircle_x402_pay
| circle_wallet_create | — | |
| circle_wallet_list | — | |
| circle_balance | — | |
| circle_policy_set | — | |
| circle_transfer_usdc | — | |
| circle_x402_pay | — |
Configuration
CIRCLE_API_KEYRequiredSecretYour Circle API key from developers.circle.com
CIRCLE_PAYOUT_ADDRESS
| Name | Description | |
|---|---|---|
| CIRCLE_API_KEY | Your Circle API key from developers.circle.com | RequiredSecret |
| CIRCLE_PAYOUT_ADDRESS | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablekinance/circle-agent-stack-mcp is public and reachablegithub.com/kinance/circle-agent-stack-mcp ↗Pass
- Package names this repository as its sourcecircle-agent-stack-mcp names kinance/circle-agent-stack-mcp as sourcenpmjs.com/package/circle-agent-stack-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-06-04github.com/kinance/circle-agent-stack-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from circle-agent-stack-mcpPass
- No critical advisory in the package or its dependencies153 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcircle-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-mcp
Tools
| Tool | What it does |
|---|---|
circle_wallet_create |
Create an agent wallet (dev/hosted/smart) |
circle_wallet_list |
List wallets with USDC balances |
circle_balance |
Balance + last 10 txns for a wallet |
circle_policy_set |
Set daily cap, x402 cap, allow/block lists |
circle_transfer_usdc |
Send USDC to an on-chain address |
circle_x402_pay |
Pay an x402-priced endpoint and return its response |
Quickstart
You need the Circle CLI installed and authenticated:
npm install -g @circle-fin/circle-cli
circle login
export CIRCLE_API_KEY=your_key_here
Claude 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-mcp
Example
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:http
To 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 payments - Start on
type="dev"wallets, not mainnet - Review the
allowlistbefore moving to production - Don't commit
CIRCLE_API_KEY
Roadmap
-
circle_nanopayment_stream— streaming x402 payments for per-token billing -
circle_skills_list/circle_skills_call— Circle Skills marketplace - Direct HTTP API mode (v0.2) — remove CLI dependency
- Multi-chain — EURC, CCTP cross-chain transfers
Related
Circle Agent Stack MCP questions
How do I add Circle Agent Stack MCP to Claude Code?
Run claude mcp add --env 'CIRCLE_API_KEY=<YOUR_CIRCLE_API_KEY>' circle-agent-stack-mcp -- npx -y circle-agent-stack-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Circle Agent Stack MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Circle Agent Stack MCP provide?
It exposes 6 tools, including circle_wallet_create, circle_wallet_list, circle_balance, circle_policy_set, circle_transfer_usdc.