io.github.HTTPayer/mcp

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