@httpayer/mcp

MCP (Model Context Protocol) server for HTTPayer. Lets AI agents call x402-enabled APIs using credit balance — no wallets, no blockchain, no Web3 knowledge required.

• Dashboard & API keys: app.httpayer.com
• npm: @httpayer/mcp
• GitHub: httpayer/mcp

Quickstart

With an AI agent (recommended)

Paste this into any MCP-compatible agent (Claude Code, Cursor, Windsurf, OpenCode...):

Set up https://httpayer.com/skill.md

The agent detects your environment and handles everything automatically.

Without an agent (manual)

1. Run setup:

npx @httpayer/mcp setup

Get your API key at app.httpayer.com when prompted.

Flags:

| Flag | Description | |------|-------------| | --key sk-live-... | Provide key non-interactively | | --client <name> | Target client: claude-code, claude-desktop, cursor, windsurf, opencode, zed, cline, warp, codex | | --scope user\|project | Claude Code scope (default: user) | | --yes / -y | Skip all prompts | | --update-key | Replace existing key |

2. Add to your client:

Claude Code:

claude mcp add httpayer --scope user -- npx -y @httpayer/mcp@latest

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "httpayer": {
      "command": "npx",
      "args": ["-y", "@httpayer/mcp@latest"]
    }
  }
}

Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline (.cline/mcp_settings.json):

{
  "mcpServers": {
    "httpayer": {
      "command": "npx",
      "args": ["-y", "@httpayer/mcp@latest"]
    }
  }
}

OpenCode (opencode.json or ~/.config/opencode/config.json):

{
  "mcp": {
    "httpayer": {
      "type": "local",
      "command": ["npx", "-y", "@httpayer/mcp@latest"],
      "enabled": true
    }
  }
}

Zed:

{
  "context_servers": {
    "httpayer": {
      "command": {
        "path": "npx",
        "args": ["-y", "@httpayer/mcp@latest"]
      }
    }
  }
}

3. Restart your client and verify:

Ask your agent: "fetch https://api.httpayer.com/demo/v1/base-weather"

A weather response means HTTPayer is working.

How it works

User prompt
    │
    ▼
AI agent (Claude Code, Cursor, Windsurf...)
    │  uses MCP tools + prompts + resources
    ▼
@httpayer/mcp (local MCP server via npx)
    │  REST calls with x-api-key header
    ▼
api.httpayer.com
    │  proxy handles x402 payment to target
    ▼
Target x402-gated API

Runtime flow

1. Your client launches the MCP server via npx -y @httpayer/mcp@latest on startup (stdio transport).
2. The server reads the API key from ~/.httpayer/mcp-config.json.
3. The agent receives the tool list, system instructions, prompts, and resources in its context.
4. When the agent calls fetch, the MCP server forwards the request to POST https://api.httpayer.com/proxy.
5. HTTPayer's proxy detects a 402, pays using your credits, retries, and returns the final response.
6. The result (status, body, headers) comes back to the agent.

MCP capabilities

This server exposes three MCP primitives so agents get context automatically — without the user having to ask.

Tools

Six tools (see full reference below).

Prompts

| Name | Description | |------|-------------| | httpayer-context | Injects full HTTPayer payment context into the agent. Clients that support prompts will load this automatically at session start. |

Compatible clients (Claude Desktop, Cursor, and others) call prompts/list on connection and inject these into the agent's context proactively.

Resources

| URI | Description | |-----|-------------| | httpayer://skill.md | Full setup guide, trigger patterns, available endpoints, and workflow. Clients can pull this on demand as grounding context. |

MCP tools reference

get_balance

Check credit balance and daily usage.

Input: none

Example response:

{
  "account_id": "account_123",
  "mainnet": {
    "credits_balance": 50000,
    "daily_limit": 100000,
    "daily_spend": 15500,
    "daily_remaining": 84500
  }
}

fetch

Make an HTTP request to any x402-enabled endpoint. Payment is handled automatically.

Input:

| Field | Type | Required | Description | |-------|------|----------|-------------| | url | string | yes | Target URL | | method | string | no | GET, POST, PUT, DELETE, PATCH — default GET | | body | object | no | JSON request body | | params | object | no | Query string parameters | | headers | object | no | Additional request headers | | timeout | number | no | Timeout in seconds, max 120 |

Example response:

{
  "status": 200,
  "body": { "data": "..." },
  "headers": { "content-type": "application/json" }
}

On 502, the response includes webhook_id for async polling.

simulate

Dry-run a fetch. Returns cost estimate without spending credits.

Input: Same as fetch (except timeout).

Example response:

{
  "requiresPayment": true,
  "proxyFeeBreakdown": {
    "targetAmount": 0.01,
    "proxyFee": 0.0003,
    "totalCreditsCharged": 10.3
  }
}

get_topup_link

Returns the dashboard URL to add credits. Show to user when balance is low.

Input: none

check_limits

Check global HTTPayer system daily limits and remaining capacity.

Input: none

get_webhook_status

Poll the status of an async operation. Use when fetch returns a 502 with webhook_id.

Input: webhook_id (string, required)

Status values: pending, success, success_refunded, payment_failed, upstream_error, internal_error, rate_limited

HTTPayer API reference

Authentication: x-api-key: sk-live-... header on all requests.

| Method | Path | Tool | |--------|------|------| | GET | /v1/credits/balance | get_balance | | POST | /proxy | fetch | | POST | /proxy/sim | simulate | | GET | /limits | check_limits | | GET | /webhooks/{id} | get_webhook_status |

Proxy endpoint

POST https://api.httpayer.com/proxy

{
  "api_url": "https://target.example.com/endpoint",
  "method": "GET",
  "json": { "key": "value" },
  "params": { "query": "param" },
  "headers": { "Custom-Header": "value" },
  "timeout": 30
}

Only api_url and method are required.

Status codes:

| Code | Meaning | |------|---------| | 200 | Success | | 402 | Insufficient credits | | 429 | Rate limited | | 500 | Proxy error | | 502 | Target refused payment — includes webhook_id |

Configuration

API key stored at: ~/.httpayer/mcp-config.json

{ "apiKey": "sk-live-..." }

To update: npx @httpayer/mcp setup --update-key

x402 protocol overview

x402 is an HTTP-native micropayment protocol using the 402 Payment Required status code.

Without HTTPayer:

1. Client hits endpoint → gets 402 + payment requirements
2. Client pays on-chain (requires wallet + USDC)
3. Client retries with payment proof

With HTTPayer:

1. Client calls POST /proxy { api_url, method, ... }
2. HTTPayer detects 402, pays using your credits
3. HTTPayer retries and returns the final response

All blockchain interaction happens on HTTPayer's side.

Credit system

| Unit | Value | |------|-------| | 1 credit | 0.001 USDC | | 1 USDC | 1,000 credits | | Proxy fee | 3% of target payment |

Top up at app.httpayer.com. Below 100 credits, the agent will prompt you to top up.

Error handling

Setup errors

| Situation | Behavior | |-----------|----------| | Key format invalid | Print error, exit 1 | | Key rejected (401) | Print "API key rejected", exit 1 | | Network unreachable | Print reason, exit 1 |

MCP tool errors

All errors return isError: true — the server stays alive and the agent gets a readable message.

| Situation | Message | |-----------|---------| | No config | "No HTTPayer API key configured. Run: npx @httpayer/mcp setup" | | API non-2xx | "HTTPayer {status}: {body}" | | Unknown tool | "Unknown tool: {name}" |

© 2026 HTTPayer Inc.