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:

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

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

Resources

---

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.