// mcp.md

> MCP Server

// Integrate EntRoute directly into Claude and other MCP-compatible AI agents.

// install + run
npx @entroute/mcp-server
// claude code (CLI)

Add the MCP server with a single command:

claude mcp add --transport stdio entroute -- npx @entroute/mcp-server

This adds the server to your project's .mcp.json. Use --scope user to make it available across all projects.

// claude desktop (app)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "entroute": {
      "command": "npx",
      "args": ["@entroute/mcp-server"]
    }
  }
}
// environment variables

Configure the MCP server with environment variables. Set EVM_PRIVATE_KEY to enable automatic x402 payments.

Variable Default Description
ENTROUTE_API_URL http://localhost:8787 EntRoute API base URL
EVM_PRIVATE_KEY - Hex private key (0x...) for x402 payments
MAX_PAYMENT_PER_REQUEST 0.05 Max USD per API call
// config with payments enabled

To enable automatic x402 payments, pass the private key and spending limit via environment.

Claude Code:

claude mcp add --transport stdio entroute \
  --env ENTROUTE_API_URL=https://api.entroute.com \
  --env EVM_PRIVATE_KEY=0x... \
  --env MAX_PAYMENT_PER_REQUEST=0.05 \
  -- npx @entroute/mcp-server

Claude Desktop:

{
  "mcpServers": {
    "entroute": {
      "command": "npx",
      "args": ["@entroute/mcp-server"],
      "env": {
        "ENTROUTE_API_URL": "https://api.entroute.com",
        "EVM_PRIVATE_KEY": "0x...",
        "MAX_PAYMENT_PER_REQUEST": "0.05"
      }
    }
  }
}
// available tools
tool discover_paid_api

Find pay-per-request API endpoints for a given capability or intent.

Parameters:

  • capability_id — dotted capability ID (e.g. "defi.token_price")
  • intent — natural language description of what you need
  • max_price — maximum price per call in USD (optional)
  • network — payment network: base, ethereum, etc. (optional)
  • ranking_preset — default, reliability, speed, or budget (optional)
tool list_capabilities

List all available capabilities in the EntRoute registry.

Parameters:

  • tag — filter by tag (optional)
  • search — search by keyword (optional)
tool call_paid_api

Call a discovered endpoint. When EVM_PRIVATE_KEY is set, automatically handles x402 payment challenges (signs via EIP-3009 and retries). Without a key, 402 responses return an error with payment details.

Parameters:

  • endpoint_id — endpoint ID from a discover_paid_api result
  • method — HTTP method override (optional)
  • body — request body for POST/PUT/PATCH (optional)
  • query_params — URL query parameters (optional)
  • headers — additional HTTP headers (optional)
// example usage in Claude

User: What's the current price of ETH?

Claude: Let me find an API for that.

→ Calls discover_paid_api with intent "get ETH token price"

→ Receives ranked endpoints with pricing

→ Calls call_paid_api with the top endpoint_id

→ x402 payment handled automatically (if wallet configured)

→ Returns price data + payment receipt

// x402 payment flow

When EVM_PRIVATE_KEY is set, the MCP server handles the x402 v2 payment protocol automatically:

1. Agent calls call_paid_api with an endpoint_id

2. Server checks price against MAX_PAYMENT_PER_REQUEST limit

3. Server calls the endpoint; if it returns 402, the SDK signs payment via EIP-3009

4. Request is retried with PAYMENT-SIGNATURE header

5. Response includes both the API data and a payment receipt

Without a private key, 402 responses return a structured error with payment details and a hint to configure the key.

TypeScript SDK Back to Docs