@valeo/mcp

Give any AI agent the ability to pay for APIs, manage wallets, get credit, and track spending.

One MCP server. Every payment tool an agent needs.

Quick start

1. Install / run — MCP clients typically spawn the server via npx (no global install required):

   npx -y @valeo/mcp

2. Configure — Add to Claude Desktop claude_desktop_config.json:

   {
     "mcpServers": {
       "valeo": {
         "command": "npx",
         "args": ["-y", "@valeo/mcp"],
         "env": {
           "VALEO_PRIVATE_KEY": "0x...",
           "VALEO_CHAIN": "base",
           "VALEO_ACE_API_KEY": "sk_...",
           "VALEO_SENTINEL_API_KEY": "sk_..."
         }
       }
     }
   }

3. Use — Ask the agent to discover paid APIs (discover_apis), check price (estimate_cost), then call them (pay). The server negotiates HTTP 402, signs, and settles via x402.

Tools reference

| Tool | Description | |------|-------------| | pay | Call an x402-enabled URL; handles 402, payment, retry, receipts, and budget checks. | | wallet_balance | USDC + gas (ETH or SOL) for Base or Solana (same chain family as VALEO_CHAIN). | | get_credit | Request ACE credit when the wallet is short (requires VALEO_ACE_API_KEY). | | repay_credit | Repay an ACE loan by loan_id (requires ACE key). | | spending_history | Sentinel audit trail if configured; otherwise session receipts. | | discover_apis | Search the 402.md registry by query, category, chain, and max price. | | set_budget | Per-call, daily, and session limits; optional allow/block URL patterns. | | estimate_cost | GET probe for pricing without paying; compares budget and wallet. |

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | VALEO_PRIVATE_KEY | Yes | — | EVM: 0x + 64 hex (66 chars). Solana: base58 secret (64 bytes). | | VALEO_CHAIN | No | base | base, base-sepolia, solana, solana-devnet | | VALEO_ACE_API_KEY | No | — | Enables get_credit / repay_credit | | VALEO_SENTINEL_API_KEY | No | — | Full spending_history via Sentinel | | VALEO_SOLANA_RPC_URL | No | public RPC | Custom Solana RPC | | VALEO_ACE_BASE_URL | No | https://api.agentcreditengine.com | ACE API base | | VALEO_SENTINEL_BASE_URL | No | https://sentinel.valeocash.com | Sentinel API base | | VALEO_402MD_BASE_URL | No | https://402md.valeoprotocol.io | 402.md registry | | VALEO_FACILITATOR_URL | No | https://x402.org/facilitator | Documented default facilitator | | VALEO_MAX_PER_CALL | No | 1.00 | Default max USDC per call | | VALEO_DAILY_LIMIT | No | 50.00 | Default daily USDC cap | | VALEO_SESSION_LIMIT | No | 10.00 | Default session USDC cap |

Copy .env.example as a template.

Supported chains

• Base (mainnet) and Base Sepolia (testnet) — USDC via viem + x402-fetch.
• Solana (mainnet) and Solana devnet — USDC SPL + x402-solana.

You cannot mix EVM and Solana keys on one server: wallet_balance only allows overrides within the same family as VALEO_CHAIN.

How it works

1. Client calls a URL. If the resource is free, you get 200 and payment: null.
2. If the server responds 402 with x402 accepts metadata, the server checks budget rules, then uses a chain-specific x402 client to sign and attach payment, retrying the request.
3. Successful spends are recorded in-memory (receipts) and reflected in budget totals. Optional Sentinel key adds remote audit history.

Valeo ecosystem

• ACE — Agent Credit Engine for short-term USDC credit.
• Sentinel — Payment audit trail and transaction history.
• 402.md — Discovery registry for x402 manifests.
• Stratum — Settlement layer in the broader Valeo stack (see valeocash.com / product docs).

Example conversations

1. Simple paid call

• User: “Get premium data from https://api.example.com/v1/data.”
• Agent: Calls pay → “Here is the JSON payload. Paid $0.01 USDC on Base. Session budget remaining: $9.99.”

2. Credit flow

• User: “I need market data but I’m low on USDC.”
• Agent: wallet_balance → get_credit → pay → “Borrowed USDC via ACE, fetched data, auto-repay rules apply per ACE.”

3. Discovery + budget

• User: “Find cheap weather APIs and cap me at $2 today.”
• Agent: set_budget → discover_apis → estimate_cost → “Three APIs under $0.01/call; roughly 200 calls within your daily cap.”

Verification

cd valeo-mcp
npm install
npm run build
npm run lint
node bin/valeo-mcp.js

With MCP Inspector:

VALEO_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
  VALEO_CHAIN=base-sepolia \
  npx @modelcontextprotocol/inspector node bin/valeo-mcp.js

Publish

npm login
npm publish --access public

Smoke test after publish:

npx -y @valeo/mcp

Important notes

• stdout is reserved for MCP JSON-RPC. All diagnostics use stderr (console.error).
• Daily budget resets at midnight UTC; session totals reset when the process restarts.
• If both allowlist and blocklist could apply, a non-empty allowlist wins; blocklist is ignored until allowlist is cleared.
• ACE / Sentinel / 402.md responses are parsed defensively; tools return JSON errors with suggestion instead of crashing the server.

License

MIT — see LICENSE (Valeo Technology LLC).