@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:

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
    ▼
@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 and system instructions 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 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:

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.

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:

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

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

Error handling

Setup errors

MCP tool errors

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

© 2026 HTTPayer Inc.