@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:**```bash
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 · 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:```bash
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):```json
{
"mcpServers": {
"httpayer": {
"command": "npx",
"args": ["-y", "@httpayer/mcp@latest"]
}
}
}
Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline (.cline/mcp_settings.json):```json
{
"mcpServers": {
"httpayer": {
"command": "npx",
"args": ["-y", "@httpayer/mcp@latest"]
}
}
}
**OpenCode** (`opencode.json` or `~/.config/opencode/config.json`):```json
{
"mcp": {
"httpayer": {
"type": "local",
"command": ["npx", "-y", "@httpayer/mcp@latest"],
"enabled": true
}
}
}
Zed:```json
{
"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
- Your client launches the MCP server via
npx -y @httpayer/mcp@lateston startup (stdio transport). - The server reads the API key from
~/.httpayer/mcp-config.json. - The agent receives the tool list, system instructions, prompts, and resources in its context.
- When the agent calls
fetch, the MCP server forwards the request toPOST https://api.httpayer.com/proxy. - HTTPayer's proxy detects a 402, pays using your credits, retries, and returns the final response.
- 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:```json
{
"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:**```json
{
"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:```json
{
"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````json
{
"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`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.
