mcpField
C
circle-agent-stack-mcp

circle-agent-stack-mcp

Local
github.com/kinanceFinance1Updated 21w ago
Repository

About circle-agent-stack-mcp

circle-agent-stack-mcp is an MCP server for managing Circle agent wallets and USDC payments. It provides wallet controls, spending policies, transfers, and x402 endpoint payments through MCP tools.

Key features

  1. 01Create and list agent wallets
  2. 02Check USDC balances and recent transactions
  3. 03Set spending caps and allow/block lists
  4. 04Transfer USDC on-chain
  5. 05Pay x402 endpoints

Use cases

  1. 01Create a wallet for an AI agent
  2. 02Limit automated spending with policies
  3. 03Send USDC to an on-chain address
  4. 04Pay for an x402-priced endpoint

MCP support

Exposes Circle wallet, policy, transfer, and x402 payment operations as tools for MCP clients. It shells out to the Circle CLI for operations.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "kinance-circle-agent-stack": {
      "command": "npx",
      "args": [
        "-y",
        "circle-agent-stack-mcp"
      ],
      "env": {
        "CIRCLE_API_KEY": "<CIRCLE_API_KEY>"
      }
    }
  }
}
Run commandnpx -y circle-agent-stack-mcp
Environment variables to set
CIRCLE_API_KEYSecretYour Circle API key from developers.circle.com

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmcircle-agent-stack-mcp0.1.1

Tools

6

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
namestringYesHuman-readable wallet name (e.g. 'eva-treasury')
typeenumNoWallet type: 'dev' for testnet, 'hosted' for custodial, 'smart' for on-chain programmablesmart | hosted | dev

Details

From the project README

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-mcp

Tools

ToolWhat it does
circle_wallet_createCreate an agent wallet (dev/hosted/smart)
circle_wallet_listList wallets with USDC balances
circle_balanceBalance + last 10 txns for a wallet
circle_policy_setSet daily cap, x402 cap, allow/block lists
circle_transfer_usdcSend USDC to an on-chain address
circle_x402_payPay 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_usdc before enabling automated payments
  • Start on type="dev" wallets, not mainnet
  • Review the allowlist before 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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.