{
  "markdown": "# @httpayer/mcp\n\nMCP (Model Context Protocol) server for HTTPayer. Lets AI agents call x402-enabled APIs using credit balance — no wallets, no blockchain, no Web3 knowledge required.\n\n- Dashboard & API keys: [app.httpayer.com](https://app.httpayer.com)\n- npm: [@httpayer/mcp](https://www.npmjs.com/package/@httpayer/mcp)\n- GitHub: [httpayer/mcp](https://github.com/httpayer/mcp)\n\n---\n\n## Quickstart\n\n### With an AI agent (recommended)\n\nPaste this into any MCP-compatible agent (Claude Code, Cursor, Windsurf, OpenCode...):\n\n```\nSet up https://httpayer.com/skill.md\n```\n\nThe agent detects your environment and handles everything automatically.\n\n### Without an agent (manual)\n\n**1. Run setup:**\n```bash\nnpx @httpayer/mcp setup\n```\n\nGet your API key at [app.httpayer.com](https://app.httpayer.com) when prompted.\n\nFlags:\n\n| Flag | Description |\n|------|-------------|\n| `--key sk-live-...` | Provide key non-interactively |\n| `--client <name>` | Target client: `claude-code`, `claude-desktop`, `cursor`, `windsurf`, `opencode`, `zed`, `cline`, `warp`, `codex` |\n| `--scope user\\|project` | Claude Code scope (default: `user`) |\n| `--yes` / `-y` | Skip all prompts |\n| `--update-key` | Replace existing key |\n\n**2. Add to your client:**\n\n**Claude Code:**\n```bash\nclaude mcp add httpayer --scope user -- npx -y @httpayer/mcp@latest\n```\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n```json\n{\n  \"mcpServers\": {\n    \"httpayer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@httpayer/mcp@latest\"]\n    }\n  }\n}\n```\n\n**Cursor** (`.cursor/mcp.json`), **Windsurf** (`.windsurf/mcp.json`), **Cline** (`.cline/mcp_settings.json`):\n```json\n{\n  \"mcpServers\": {\n    \"httpayer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@httpayer/mcp@latest\"]\n    }\n  }\n}\n```\n\n**OpenCode** (`opencode.json` or `~/.config/opencode/config.json`):\n```json\n{\n  \"mcp\": {\n    \"httpayer\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@httpayer/mcp@latest\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n**Zed:**\n```json\n{\n  \"context_servers\": {\n    \"httpayer\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@httpayer/mcp@latest\"]\n      }\n    }\n  }\n}\n```\n\n**3. Restart your client and verify:**\n\nAsk your agent: *\"fetch https://api.httpayer.com/demo/v1/base-weather\"*\n\nA weather response means HTTPayer is working.\n\n---\n\n## How it works\n\n```\nUser prompt\n    │\n    ▼\nAI agent (Claude Code, Cursor, Windsurf...)\n    │  uses MCP tools + prompts + resources\n    ▼\n@httpayer/mcp (local MCP server via npx)\n    │  REST calls with x-api-key header\n    ▼\napi.httpayer.com\n    │  proxy handles x402 payment to target\n    ▼\nTarget x402-gated API\n```\n\n### Runtime flow\n\n1. Your client launches the MCP server via `npx -y @httpayer/mcp@latest` on startup (stdio transport).\n2. The server reads the API key from `~/.httpayer/mcp-config.json`.\n3. The agent receives the tool list, system instructions, prompts, and resources in its context.\n4. When the agent calls `fetch`, the MCP server forwards the request to `POST https://api.httpayer.com/proxy`.\n5. HTTPayer's proxy detects a 402, pays using your credits, retries, and returns the final response.\n6. The result (status, body, headers) comes back to the agent.\n\n---\n\n## MCP capabilities\n\nThis server exposes three MCP primitives so agents get context automatically — without the user having to ask.\n\n### Tools\n\nSix tools (see full reference below).\n\n### Prompts\n\n| Name | Description |\n|------|-------------|\n| `httpayer-context` | Injects full HTTPayer payment context into the agent. Clients that support prompts will load this automatically at session start. |\n\nCompatible clients (Claude Desktop, Cursor, and others) call `prompts/list` on connection and inject these into the agent's context proactively.\n\n### Resources\n\n| URI | Description |\n|-----|-------------|\n| `httpayer://skill.md` | Full setup guide, trigger patterns, available endpoints, and workflow. Clients can pull this on demand as grounding context. |\n\n---\n\n## MCP tools reference\n\n### `get_balance`\n\nCheck credit balance and daily usage.\n\n**Input:** none\n\n**Example response:**\n```json\n{\n  \"account_id\": \"account_123\",\n  \"mainnet\": {\n    \"credits_balance\": 50000,\n    \"daily_limit\": 100000,\n    \"daily_spend\": 15500,\n    \"daily_remaining\": 84500\n  }\n}\n```\n\n---\n\n### `fetch`\n\nMake an HTTP request to any x402-enabled endpoint. Payment is handled automatically.\n\n**Input:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `url` | string | yes | Target URL |\n| `method` | string | no | `GET`, `POST`, `PUT`, `DELETE`, `PATCH` — default `GET` |\n| `body` | object | no | JSON request body |\n| `params` | object | no | Query string parameters |\n| `headers` | object | no | Additional request headers |\n| `timeout` | number | no | Timeout in seconds, max 120 |\n\n**Example response:**\n```json\n{\n  \"status\": 200,\n  \"body\": { \"data\": \"...\" },\n  \"headers\": { \"content-type\": \"application/json\" }\n}\n```\n\nOn 502, the response includes `webhook_id` for async polling.\n\n---\n\n### `simulate`\n\nDry-run a fetch. Returns cost estimate without spending credits.\n\n**Input:** Same as `fetch` (except `timeout`).\n\n**Example response:**\n```json\n{\n  \"requiresPayment\": true,\n  \"proxyFeeBreakdown\": {\n    \"targetAmount\": 0.01,\n    \"proxyFee\": 0.0003,\n    \"totalCreditsCharged\": 10.3\n  }\n}\n```\n\n---\n\n### `get_topup_link`\n\nReturns the dashboard URL to add credits. Show to user when balance is low.\n\n**Input:** none\n\n---\n\n### `check_limits`\n\nCheck global HTTPayer system daily limits and remaining capacity.\n\n**Input:** none\n\n---\n\n### `get_webhook_status`\n\nPoll the status of an async operation. Use when `fetch` returns a 502 with `webhook_id`.\n\n**Input:** `webhook_id` (string, required)\n\n**Status values:** `pending`, `success`, `success_refunded`, `payment_failed`, `upstream_error`, `internal_error`, `rate_limited`\n\n---\n\n## HTTPayer API reference\n\nAuthentication: `x-api-key: sk-live-...` header on all requests.\n\n| Method | Path | Tool |\n|--------|------|------|\n| `GET` | `/v1/credits/balance` | `get_balance` |\n| `POST` | `/proxy` | `fetch` |\n| `POST` | `/proxy/sim` | `simulate` |\n| `GET` | `/limits` | `check_limits` |\n| `GET` | `/webhooks/{id}` | `get_webhook_status` |\n\n### Proxy endpoint\n\n`POST https://api.httpayer.com/proxy`\n\n```json\n{\n  \"api_url\": \"https://target.example.com/endpoint\",\n  \"method\": \"GET\",\n  \"json\": { \"key\": \"value\" },\n  \"params\": { \"query\": \"param\" },\n  \"headers\": { \"Custom-Header\": \"value\" },\n  \"timeout\": 30\n}\n```\n\nOnly `api_url` and `method` are required.\n\n**Status codes:**\n\n| Code | Meaning |\n|------|---------|\n| `200` | Success |\n| `402` | Insufficient credits |\n| `429` | Rate limited |\n| `500` | Proxy error |\n| `502` | Target refused payment — includes `webhook_id` |\n\n---\n\n## Configuration\n\nAPI key stored at: `~/.httpayer/mcp-config.json`\n\n```json\n{ \"apiKey\": \"sk-live-...\" }\n```\n\nTo update: `npx @httpayer/mcp setup --update-key`\n\n---\n\n## x402 protocol overview\n\nx402 is an HTTP-native micropayment protocol using the `402 Payment Required` status code.\n\n**Without HTTPayer:**\n1. Client hits endpoint → gets `402` + payment requirements\n2. Client pays on-chain (requires wallet + USDC)\n3. Client retries with payment proof\n\n**With HTTPayer:**\n1. Client calls `POST /proxy { api_url, method, ... }`\n2. HTTPayer detects `402`, pays using your credits\n3. HTTPayer retries and returns the final response\n\nAll blockchain interaction happens on HTTPayer's side.\n\n---\n\n## Credit system\n\n| Unit | Value |\n|------|-------|\n| 1 credit | 0.001 USDC |\n| 1 USDC | 1,000 credits |\n| Proxy fee | 3% of target payment |\n\nTop up at [app.httpayer.com](https://app.httpayer.com). Below 100 credits, the agent will prompt you to top up.\n\n---\n\n## Error handling\n\n### Setup errors\n\n| Situation | Behavior |\n|-----------|----------|\n| Key format invalid | Print error, exit 1 |\n| Key rejected (401) | Print \"API key rejected\", exit 1 |\n| Network unreachable | Print reason, exit 1 |\n\n### MCP tool errors\n\nAll errors return `isError: true` — the server stays alive and the agent gets a readable message.\n\n| Situation | Message |\n|-----------|---------|\n| No config | `\"No HTTPayer API key configured. Run: npx @httpayer/mcp setup\"` |\n| API non-2xx | `\"HTTPayer {status}: {body}\"` |\n| Unknown tool | `\"Unknown tool: {name}\"` |\n\n---\n\n© 2026 HTTPayer Inc.\n",
  "bytes": 8405,
  "sha": "b495f7d3ac134d722d85446bf45546b933b5f4b3ca2157852136f545a66cc754",
  "repo_slug": "httpayer/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_httpayer_mcp_0420bca0/readme"
}