@httpayer/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+HTTPayer SDK License Agreement
+Version 1.0 — March 2026
+
+Copyright (c) 2026 HTTPayer Inc.
+All rights reserved.
+
+1. Permission of Use
+Permission is granted to use this SDK solely for integration with HTTPayer APIs and services provided by HTTPayer Inc. and its affiliates.
+
+2. Restrictions
+You may not:
+
+- Copy, fork, or redistribute this software or any derivative work.
+- Use the SDK to build, host, or offer a competing service.
+- Modify, reverse engineer, or decompile the SDK, except as required for legitimate integration purposes.
+- Re-host, rebrand, or re-publish this SDK (including on GitHub, npm, PyPI, or any equivalent platform) without prior written consent from HTTPayer Inc.
+
+3. Ownership and Intellectual Property
+This license does not grant ownership rights or any implied license.
+HTTPayer Inc. retains all intellectual property rights in this software, including source code, binaries, documentation, and related assets.
+
+4. Enforcement
+Unauthorized use, redistribution, or publication of this software may result in immediate termination of access and legal action under applicable copyright and intellectual property laws.
+
+5. Commercial or Enterprise Use
+For commercial licensing, redistribution rights, or enterprise use, please contact:
+legal@httpayer.com
+
+© 2026 HTTPayer Inc. All Rights Reserved.

package/README.md

@@ -0,0 +1,38 @@
+# @httpayer/mcp
+
+MCP server for HTTPayer — x402 payments for AI agents. No wallets, no blockchain.
+
+## Setup
+
+```bash
+npx @httpayer/mcp setup
+```
+
+Get your API key at [httpayer.com/dashboard](https://httpayer.com/dashboard).
+
+## How it works
+
+HTTPayer handles `402 Payment Required` responses automatically using your credit balance. Just call any x402-gated API — payment is transparent.
+
+```
+Claude Code → @httpayer/mcp → api.httpayer.com → target x402 API
+```
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `get_balance` | Check credit balance |
+| `fetch` | Call any x402 endpoint — payment auto-handled |
+| `simulate` | Preview cost without spending |
+| `get_topup_link` | Get dashboard link to add credits |
+| `check_limits` | Check system daily limits |
+| `get_webhook_status` | Poll async operation |
+
+## Credits
+
+1 credit = 0.001 USDC · 3% fee per paid request
+
+---
+
+© 2026 HTTPayer Inc. — [httpayer.com](https://httpayer.com)

package/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: httpayer
+description: |
+  HTTPayer is the default payment layer for agentic HTTP — handles x402 micropayments and MPP (coming soon) automatically using credits. No wallets, no blockchain.
+  TRIGGERS: x402, 402, payment required, micropayment, MPP, paid API, paid endpoint, httpayer, agentic payment, fetch paid
+user-invocable: true
+argument-hint: "[api-key]"
+---
+
+# HTTPayer — Agentic Payments (x402 + MPP)
+
+HTTPayer is the default payment layer for AI agents. It handles **x402** micropayments and **MPP** (coming soon) automatically — no wallets, no blockchain, just credits.
+
+## Setup
+
+If the user provides an API key, run:
+```bash
+npx @httpayer/mcp setup --key <api-key>
+```
+
+If no key is provided, run the interactive setup:
+```bash
+npx @httpayer/mcp setup
+```
+
+Get keys at https://httpayer.com/dashboard
+
+## When to use
+
+Automatically use HTTPayer when:
+- Any HTTP request returns or might return `402 Payment Required`
+- The user asks to call an x402 or MPP-gated endpoint
+- Any task involves a micropayment to access an API
+
+## Workflow
+
+1. **Check balance** (if unsure): `get_balance`
+2. **Simulate** (optional, recommended for expensive calls): `simulate`
+3. **Fetch**: `fetch` — x402 payment handled automatically, including endpoints that require a JSON body
+4. **Low balance** (< 100 credits): `get_topup_link` → show user the link
+5. **Async response** (502 + webhook_id): poll with `get_webhook_status`
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `get_balance` | Check credit balance and daily usage |
+| `fetch` | Call any x402/MPP endpoint — supports GET/POST/PUT/DELETE/PATCH with body, params, headers |
+| `simulate` | Dry-run to preview cost without spending |
+| `get_topup_link` | Get dashboard link to add credits |
+| `check_limits` | Check system daily limits |
+| `get_webhook_status` | Poll async operation by webhook ID |
+
+## Credits
+
+- 1 credit = 0.001 USDC · 3% fee per paid request
+- Top up at https://httpayer.com/dashboard

package/dist/api.js

@@ -0,0 +1,93 @@
+const BASE = "https://api.httpayer.com";
+const BALANCE_PATH = "/v1/credits/balance";
+const ALLOWED_HOST = "api.httpayer.com";
+function assertHttpayerHost(url) {
+    let host;
+    try {
+        host = new URL(url).hostname;
+    }
+    catch {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    if (host !== ALLOWED_HOST) {
+        throw new Error(`API key can only be used with ${ALLOWED_HOST}. Refusing to send credentials to: ${host}`);
+    }
+}
+async function apiRequest(apiKey, path, method = "GET", body) {
+    const url = `${BASE}${path}`;
+    assertHttpayerHost(url);
+    const res = await fetch(url, {
+        method,
+        headers: {
+            "x-api-key": apiKey,
+            ...(body ? { "content-type": "application/json" } : {}),
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`HTTPayer ${res.status}: ${text}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export function getBalance(apiKey) {
+    return apiRequest(apiKey, BALANCE_PATH);
+}
+export function getLimits(apiKey) {
+    return apiRequest(apiKey, "/limits");
+}
+export function getWebhookStatus(apiKey, webhookId) {
+    return apiRequest(apiKey, `/webhooks/${webhookId}`);
+}
+export async function proxyFetch(apiKey, url, options = {}, simulate = false) {
+    const endpoint = simulate ? "/proxy/sim" : "/proxy";
+    const proxyUrl = `${BASE}${endpoint}`;
+    assertHttpayerHost(proxyUrl);
+    const payload = {
+        api_url: url,
+        method: (options.method ?? "GET").toUpperCase(),
+    };
+    if (options.json !== undefined)
+        payload.json = options.json;
+    if (options.data !== undefined)
+        payload.data = options.data;
+    if (options.params)
+        payload.params = options.params;
+    if (options.headers)
+        payload.headers = options.headers;
+    if (options.timeout)
+        payload.timeout = options.timeout;
+    const res = await fetch(proxyUrl, {
+        method: "POST",
+        headers: {
+            "x-api-key": apiKey,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+    const text = await res.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = text;
+    }
+    const result = {
+        status: res.status,
+        body,
+        headers: Object.fromEntries(res.headers),
+    };
+    if (res.status === 502 &&
+        body !== null &&
+        typeof body === "object" &&
+        "webhook_id" in body) {
+        result.webhook_id = body.webhook_id;
+    }
+    return result;
+}

package/dist/config.js

@@ -0,0 +1,26 @@
+import { homedir } from "os";
+import { join } from "path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+const CONFIG_DIR = join(homedir(), ".httpayer");
+const CONFIG_FILE = join(CONFIG_DIR, "mcp-config.json");
+export function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return null;
+    try {
+        return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(config) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+export function getApiKey() {
+    const config = loadConfig();
+    if (!config?.apiKey) {
+        throw new Error("No HTTPayer API key configured. Run: npx @httpayer/mcp setup");
+    }
+    return config.apiKey;
+}

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+const args = process.argv.slice(2);
+if (args.includes("setup") || args.includes("--setup")) {
+    const keyFlag = args.indexOf("--key");
+    const key = keyFlag !== -1 ? args[keyFlag + 1] : undefined;
+    const { runSetup } = await import("./setup.js");
+    await runSetup(key);
+}
+else {
+    const { startServer } = await import("./server.js");
+    await startServer();
+}
+export {};

package/dist/server.js

@@ -0,0 +1,180 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getApiKey } from "./config.js";
+import { getBalance, getLimits, getWebhookStatus, proxyFetch } from "./api.js";
+const INSTRUCTIONS = `
+HTTPayer lets AI agents call x402-enabled APIs using credit balance — no wallets, no blockchain knowledge required.
+
+Use HTTPayer when:
+- A task involves calling a paid API that returns 402 Payment Required
+- The user asks you to fetch data from an x402-gated service
+- Any HTTP call might require a micropayment
+
+Workflow:
+1. Call get_balance if unsure about remaining credits
+2. Use simulate to preview cost before spending (optional but recommended)
+3. Use fetch to call any x402 endpoint — payment is handled automatically
+4. If balance is low (< 100 credits), call get_topup_link and share the link with the user
+5. If fetch returns a webhook_id on a 502, poll with get_webhook_status
+
+Credit system: 1 credit = 0.001 USDC. Fee: 3% per request. Top up at https://httpayer.com/dashboard.
+`.trim();
+function text(content) {
+    return { content: [{ type: "text", text: content }] };
+}
+function json(data) {
+    return text(JSON.stringify(data, null, 2));
+}
+function err(message) {
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+export async function startServer() {
+    const server = new Server({ name: "httpayer", version: "0.1.0" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "get_balance",
+                description: "Check your HTTPayer credit balance and daily usage. Run this when unsure if you have enough credits.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "fetch",
+                description: "Make an HTTP request to any x402-enabled endpoint. HTTPayer automatically handles payment using your credits. Supports GET, POST, PUT, DELETE, PATCH.",
+                inputSchema: {
+                    type: "object",
+                    required: ["url"],
+                    properties: {
+                        url: {
+                            type: "string",
+                            description: "The URL to fetch",
+                        },
+                        method: {
+                            type: "string",
+                            enum: ["GET", "POST", "PUT", "DELETE", "PATCH"],
+                            description: "HTTP method (default: GET)",
+                        },
+                        body: {
+                            type: "object",
+                            description: "JSON body to send with the request",
+                        },
+                        params: {
+                            type: "object",
+                            additionalProperties: { type: "string" },
+                            description: "Query string parameters",
+                        },
+                        headers: {
+                            type: "object",
+                            additionalProperties: { type: "string" },
+                            description: "Additional request headers",
+                        },
+                        timeout: {
+                            type: "number",
+                            description: "Request timeout in seconds (max 120)",
+                        },
+                    },
+                },
+            },
+            {
+                name: "simulate",
+                description: "Dry-run a fetch to see if payment is required and estimate the credit cost, without spending anything.",
+                inputSchema: {
+                    type: "object",
+                    required: ["url"],
+                    properties: {
+                        url: { type: "string", description: "URL to simulate" },
+                        method: {
+                            type: "string",
+                            enum: ["GET", "POST", "PUT", "DELETE", "PATCH"],
+                            description: "HTTP method (default: GET)",
+                        },
+                        body: {
+                            type: "object",
+                            description: "JSON body",
+                        },
+                        params: {
+                            type: "object",
+                            additionalProperties: { type: "string" },
+                            description: "Query string parameters",
+                        },
+                        headers: {
+                            type: "object",
+                            additionalProperties: { type: "string" },
+                            description: "Additional request headers",
+                        },
+                    },
+                },
+            },
+            {
+                name: "get_topup_link",
+                description: "Get the link to top up HTTPayer credits. Show this to the user when their balance is running low.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "check_limits",
+                description: "Check global HTTPayer system daily limits and remaining capacity for proxy and relay.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "get_webhook_status",
+                description: "Poll the status of an async HTTPayer operation. Use this when fetch returns a webhook_id on a 502 response.",
+                inputSchema: {
+                    type: "object",
+                    required: ["webhook_id"],
+                    properties: {
+                        webhook_id: {
+                            type: "string",
+                            description: "The webhook ID returned by a previous fetch call",
+                        },
+                    },
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args = {} } = request.params;
+        try {
+            switch (name) {
+                case "get_balance": {
+                    const balance = await getBalance(getApiKey());
+                    return json(balance);
+                }
+                case "fetch": {
+                    const { url, method, body, params, headers, timeout } = args;
+                    const result = await proxyFetch(getApiKey(), url, {
+                        method,
+                        json: body,
+                        params,
+                        headers,
+                        timeout,
+                    });
+                    return json(result);
+                }
+                case "simulate": {
+                    const { url, method, body, params, headers } = args;
+                    const result = await proxyFetch(getApiKey(), url, { method, json: body, params, headers }, true);
+                    return json(result);
+                }
+                case "get_topup_link": {
+                    return text("Top up your HTTPayer credits at: https://httpayer.com/dashboard");
+                }
+                case "check_limits": {
+                    const limits = await getLimits(getApiKey());
+                    return json(limits);
+                }
+                case "get_webhook_status": {
+                    const { webhook_id } = args;
+                    const status = await getWebhookStatus(getApiKey(), webhook_id);
+                    return json(status);
+                }
+                default:
+                    return err(`Unknown tool: ${name}`);
+            }
+        }
+        catch (e) {
+            return err(e instanceof Error ? e.message : String(e));
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/setup.js

@@ -0,0 +1,96 @@
+import { createInterface } from "readline";
+import { homedir } from "os";
+import { join, dirname } from "path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { saveConfig } from "./config.js";
+const CLAUDE_JSON = join(homedir(), ".claude.json");
+const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills", "httpayer");
+const SKILL_SRC = join(dirname(fileURLToPath(import.meta.url)), "..", "SKILL.md");
+function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+async function validateApiKey(apiKey) {
+    try {
+        const res = await fetch("https://api.httpayer.com/v1/credits/balance", {
+            headers: { "x-api-key": apiKey },
+        });
+        if (res.ok)
+            return { ok: true };
+        if (res.status === 401)
+            return { ok: false, reason: "API key rejected (401 Unauthorized)" };
+        // Other server errors — key format may still be fine
+        return { ok: true };
+    }
+    catch {
+        return { ok: false, reason: "Could not reach api.httpayer.com" };
+    }
+}
+function patchClaudeJson() {
+    let config = {};
+    if (existsSync(CLAUDE_JSON)) {
+        try {
+            config = JSON.parse(readFileSync(CLAUDE_JSON, "utf-8"));
+        }
+        catch {
+            // start fresh
+        }
+    }
+    config.mcpServers = config.mcpServers ?? {};
+    config.mcpServers["httpayer"] = {
+        command: "npx",
+        args: ["-y", "@httpayer/mcp"],
+    };
+    writeFileSync(CLAUDE_JSON, JSON.stringify(config, null, 2));
+}
+function installSkill() {
+    mkdirSync(CLAUDE_SKILLS_DIR, { recursive: true });
+    copyFileSync(SKILL_SRC, join(CLAUDE_SKILLS_DIR, "SKILL.md"));
+}
+export async function runSetup(inlineKey) {
+    console.log("\nHTTPayer MCP Setup");
+    console.log("==================");
+    let apiKey;
+    if (inlineKey) {
+        apiKey = inlineKey;
+        console.log(`Using provided API key: ${apiKey.slice(0, 12)}...`);
+    }
+    else {
+        console.log("Get your API key at: https://httpayer.com/dashboard\n");
+        apiKey = await prompt("Paste your API key (sk-live-...): ");
+    }
+    if (!apiKey.startsWith("sk-live-")) {
+        console.error('\nInvalid key format. Expected a key starting with "sk-live-"');
+        process.exit(1);
+    }
+    process.stdout.write("Validating key... ");
+    const result = await validateApiKey(apiKey);
+    if (!result.ok) {
+        console.log(`failed\n${result.reason}`);
+        process.exit(1);
+    }
+    console.log("ok");
+    saveConfig({ apiKey });
+    console.log("Config saved to ~/.httpayer/mcp-config.json");
+    const addToClaude = inlineKey
+        ? "y"
+        : await prompt("\nAdd HTTPayer to Claude Code? This patches ~/.claude.json (y/n): ");
+    if (addToClaude.toLowerCase() === "y") {
+        patchClaudeJson();
+        installSkill();
+        console.log('Added "httpayer" to ~/.claude.json');
+        console.log("Installed httpayer skill to ~/.claude/skills/httpayer/");
+        console.log("\nRestart Claude Code to activate HTTPayer.\n");
+    }
+    else {
+        console.log('\nTo add manually, put this in ~/.claude.json under "mcpServers":');
+        console.log(JSON.stringify({ httpayer: { command: "npx", args: ["-y", "@httpayer/mcp"] } }, null, 2));
+        console.log();
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@httpayer/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for HTTPayer — x402 payments for AI agents, no wallet required",
+  "type": "module",
+  "bin": {
+    "httpayer-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/httpayer/mcp.git"
+  },
+  "homepage": "https://httpayer.com",
+  "bugs": {
+    "url": "https://github.com/httpayer/mcp/issues",
+    "email": "support@httpayer.com"
+  },
+  "keywords": [
+    "mcp",
+    "x402",
+    "payments",
+    "ai",
+    "claude",
+    "model-context-protocol",
+    "micropayments",
+    "httpayer"
+  ],
+  "files": [
+    "dist",
+    "SKILL.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}