io.github.HTTPayer/mcp
x402 micropayments for AI agents — credits-based, no wallets, no blockchain.
Open source Open in the app JSON README (API)
About
x402 micropayments for AI agents — credits-based, no wallets, no blockchain.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- httpayer
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.7
- Stars
- 2
- Last push
- 2026-04-28T01:09:02Z
- Repository state
- ativo
- Language
- TypeScript
- License
- NOASSERTION
- Added
- 2026-08-29 03:01:56
- Updated
- 2026-08-29 03:01:56
- Origin id
io.github.HTTPayer/mcp
README
# @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](https://app.httpayer.com)
- npm: [@httpayer/mcp](https://www.npmjs.com/package/@httpayer/mcp)
- GitHub: [httpayer/mcp](https://github.com/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](https://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:**
```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
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:**
```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](https://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.