x402-agent-npm: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server that enables LLM agents to autonomously call x402-protected APIs using CDP embedded wallets. The server exposes configured x402 endpoints as MCP tools, allowing agents to discover and use paid APIs with automatic payment handling.

Development Commands

# Build TypeScript to dist/
npm run build

# Development mode with hot reload
npm run dev

# Run the compiled server
npm start

# Run directly with tsx (bypasses build)
tsx src/index.ts

Architecture Overview

Core Components

1. MCP Server Layer (src/server.ts, src/index.ts)

   • Entry point creates MCP server using @modelcontextprotocol/sdk
   • Registers two handlers: tools/list and tools/call
   • Uses stdio transport for communication with MCP clients

2. Endpoint Registry (src/registry/)

   • EndpointRegistry.ts: Loads and manages endpoint configurations from JSON
   • validator.ts: Validates configuration against schema requirements
   • types.ts: TypeScript interfaces for Config, Endpoint, WalletConfig
   • Supports environment variable interpolation (e.g., ${PRIVATE_KEY})

3. Payment System (src/payment/)

   • WalletManager.ts: Initializes CDP embedded wallets using viem
   • PaymentHandler.ts: Wraps fetch with x402-fetch for automatic payment
   • Extracts transaction hash from X-PAYMENT-RESPONSE header
   • Supports Base, Base Sepolia, Ethereum, and Sepolia networks

4. Request Handlers (src/handlers/)

   • listTools.ts: Converts endpoints to MCP tool definitions
   • callTool.ts: Validates trust, checks params, calls endpoint with payment

5. Utilities (src/utils/)

   • errors.ts: Custom error classes (ConfigError, PaymentError, TrustError, etc.)
   • logger.ts: Structured logging with transaction tracking
   • retry.ts: Exponential backoff retry logic