@xenarch/agent-mcp

Executes HTTP requests to APIs protected by HTTP 402 Payment Required status codes, automatically detecting payment requirements and routing requests through the MCP server's payment settlement layer. The server intercepts 402 responses, extracts payment metadata (amount, recipient, token), and initiates on-chain USDC micropayments on Base L2 before retrying the original request with proof-of-payment headers. This enables seamless agent-to-API interactions without manual payment handling or custodial intermediaries.

Manages cryptographic signing and submission of USDC transfers to Base L2 blockchain without holding agent private keys or funds in escrow. The server accepts payment requests with recipient address and amount, constructs ERC-20 transfer transactions, signs them using the agent's provided key material (or external signer), and broadcasts to Base L2 RPC. Settlement completes on-chain with full transparency and auditability, with no platform-controlled custody or fee extraction.

Maintains immutable transaction history of all USDC payments and API calls, logging transaction hash, timestamp, amount, recipient, and HTTP request/response details. The server stores logs in a queryable format (JSON, database) accessible through MCP tools, enabling agents and operators to audit spending, debug failed payments, and reconstruct payment flows. Logs include both on-chain transaction data and off-chain HTTP metadata.

Provides centralized configuration for payment parameters (USDC amount, recipient address, spending limits), API endpoint mappings, and RPC provider settings. Configuration is loaded from environment variables, JSON files, or environment-specific profiles, allowing operators to adjust payment rules without restarting the MCP server. Supports hot-reloading of configuration changes for zero-downtime updates.

Exposes HTTP 402 payment handling and USDC settlement as MCP tools that Claude, Cursor, LangChain, and CrewAI can discover and invoke through the standard Model Context Protocol. The server implements MCP tool schema definitions for payment-gated requests and settlement operations, allowing agents to treat paid API access as first-class capabilities alongside native tools. Integration requires no agent-side SDK changes — agents interact via standard MCP tool-calling semantics.

Intercepts HTTP responses with 402 Payment Required status codes and extracts payment metadata from response headers (x402-amount, x402-recipient, x402-token) to determine payment requirements. The server parses metadata, validates format and values, and automatically initiates payment settlement without requiring the agent to manually inspect headers or construct payment requests. This enables transparent payment handling where agents see paid API access as a seamless extension of normal HTTP requests.

Manages payment state and context across multiple agent frameworks (Claude, LangChain, CrewAI) executing in the same workflow, ensuring consistent wallet management, balance tracking, and transaction history. The server maintains a unified payment ledger accessible to all agents, preventing double-spending and enabling cross-agent payment coordination. Agents can query remaining balance, transaction history, and payment status through MCP tools without framework-specific code.

Generates cryptographic proof-of-payment headers (e.g., transaction hash, signature) after successful USDC settlement and attaches them to retry requests, allowing target APIs to verify that payment was completed. The server constructs headers containing transaction hash, block number, and optional signature proof, which APIs can validate against Base L2 blockchain state. This enables APIs to trust that payment occurred without querying the blockchain themselves.

Maintains real-time balance tracking for agent wallets by monitoring USDC transfers and caching balance state, allowing agents to query remaining funds and enforce spending limits before initiating payments. The server tracks balance changes from settlement transactions, updates cached state, and prevents payments that would exceed configured limits. Agents can query balance through MCP tools without blockchain queries, reducing latency.

Implements intelligent retry logic that distinguishes between payment failures (402 responses) and transient errors (5xx, timeouts), applying different backoff strategies for each. After successful payment settlement, the server retries the original request with proof-of-payment headers; if retry fails, it applies exponential backoff without re-attempting payment. This prevents redundant payments while ensuring requests eventually succeed or fail cleanly.

Abstracts Base L2 RPC interactions behind a configurable endpoint layer with automatic failover to secondary endpoints if primary fails. The server supports multiple RPC providers (Alchemy, Infura, public endpoints) and switches between them transparently on connection failures, ensuring payment settlement continues even if a single RPC provider is down. Implements connection pooling and health checks to detect failures quickly.

Estimates gas costs for USDC transfers on Base L2 before submission, predicting total transaction cost (gas * gwei) and allowing agents to make informed payment decisions. The server calls eth_estimateGas with the constructed transaction, fetches current Base L2 gas price, and returns cost estimate in USDC equivalent. Agents can use estimates to decide whether to proceed with payment or seek alternative APIs.