{"id":49747061,"url":"https://github.com/gatefareio/mcp-server","last_synced_at":"2026-05-26T07:00:47.444Z","repository":{"id":354685248,"uuid":"1224685654","full_name":"gatefareio/mcp-server","owner":"gatefareio","description":"MCP server for Gatefare — discover, buy, and publish paid APIs (x402 over USDC on Base) from Claude, Cursor, and any AI agent.","archived":false,"fork":false,"pushed_at":"2026-04-29T16:51:14.000Z","size":91,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T17:18:16.995Z","etag":null,"topics":["ai-agents","anthropic","api-marketplace","base","claude","coinbase","cursor","gatefare","llm-tools","mcp","mcp-server","micropayments","model-context-protocol","nodejs","paid-apis","stablecoin-payments","typescript","usdc","web3","x402"],"latest_commit_sha":null,"homepage":"https://gatefare.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gatefareio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-29T14:22:20.000Z","updated_at":"2026-04-29T16:51:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gatefareio/mcp-server","commit_stats":null,"previous_names":["gatefareio/mcp-server"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/gatefareio/mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gatefareio%2Fmcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gatefareio%2Fmcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gatefareio%2Fmcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gatefareio%2Fmcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gatefareio","download_url":"https://codeload.github.com/gatefareio/mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gatefareio%2Fmcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33508317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","anthropic","api-marketplace","base","claude","coinbase","cursor","gatefare","llm-tools","mcp","mcp-server","micropayments","model-context-protocol","nodejs","paid-apis","stablecoin-payments","typescript","usdc","web3","x402"],"created_at":"2026-05-10T06:00:23.003Z","updated_at":"2026-05-26T07:00:47.437Z","avatar_url":"https://github.com/gatefareio.png","language":"TypeScript","funding_links":[],"categories":["Uncategorized","🤖 AI Agent Integration"],"sub_categories":["Uncategorized","Model Context Protocol (MCP)"],"readme":"# @gatefare/mcp\n\n[![npm version](https://img.shields.io/npm/v/@gatefare/mcp.svg?color=cb3837\u0026logo=npm)](https://www.npmjs.com/package/@gatefare/mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@gatefare/mcp?color=cb3837)](https://www.npmjs.com/package/@gatefare/mcp)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/@gatefare/mcp?color=success)](https://bundlephobia.com/package/@gatefare/mcp)\n[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![CI](https://github.com/gatefareio/mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/gatefareio/mcp-server/actions/workflows/ci.yml)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-7C3AED?logo=anthropic)](https://registry.modelcontextprotocol.io/v0.1/servers?search=gatefareio)\n[![Base](https://img.shields.io/badge/Base-mainnet-0052FF)](https://base.org)\n\n\u003e Give your AI agent a wallet and a marketplace.\n\u003e\n\u003e `@gatefare/mcp` is a Model Context Protocol server that connects Claude\n\u003e Desktop, Cursor, or any MCP-compatible agent to the\n\u003e [Gatefare](https://gatefare.io) catalog of paid HTTP APIs. Payments\n\u003e settle as USDC on Base via the open [x402](https://x402.org) standard\n\u003e — no SaaS keys, no subscriptions, no escrow. Non-custodial: signing\n\u003e happens locally; the private key never leaves your machine.\n\n![Demo: install, list tools, real call against gatefare.io](docs/demo.gif)\n\n```\n┌─────────────┐                ┌──────────────┐                ┌─────────────────┐\n│ Claude /    │   MCP stdio    │ @gatefare/mcp│  HTTP + x402   │ gatefare.io     │\n│ Cursor /    │ ─────────────► │   (this repo)│ ─────────────► │ proxy +         │\n│ your agent  │                │              │                │ catalog         │\n└─────────────┘                └──────┬───────┘                └─────────────────┘\n                                      │\n                                      │ EIP-3009 sign\n                                      ▼\n                                ┌─────────────┐\n                                │  Base USDC  │\n                                └─────────────┘\n```\n\n## Quick start\n\n### 1. Drop into your client\n\n**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"gatefare\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@gatefare/mcp\"]\n    }\n  }\n}\n```\n\n**Cursor** — `~/.cursor/mcp.json` or project-level `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gatefare\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@gatefare/mcp\"]\n    }\n  }\n}\n```\n\nRestart the client. The agent now has 5 read-only tools — discovery + safety. Try:\n\n\u003e *\"Search Gatefare for weather APIs.\"*\n\n### 2. Add a wallet to make paid calls\n\nAdd `env` to the same config:\n\n```json\n{\n  \"mcpServers\": {\n    \"gatefare\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@gatefare/mcp\"],\n      \"env\": {\n        \"WALLET_PRIVATE_KEY\": \"0xYOUR_KEY\",\n        \"WALLET_BUDGET_USD\": \"5.00\"\n      }\n    }\n  }\n}\n```\n\nBuyer tools (`call_api`, `get_wallet_balance`, `estimate_cost`) become available. The\n`WALLET_BUDGET_USD` cap is a runtime safety net — for a hard cap, fund the wallet with\nonly what you're willing to spend.\n\n\u003e *\"What's London's weather right now? Spend up to $0.001.\"*\n\n### 3. (Optional) Publish your own APIs\n\nGet a PAT at [gatefare.io/dashboard/tokens](https://gatefare.io/dashboard/tokens) and add:\n\n```json\n\"env\": {\n  \"GATEFARE_PAT\": \"gfpat_...\"\n}\n```\n\nPublisher tools (`register_api`, `list_my_apis`, `update_api`, `get_revenue`,\n`distribute`) appear.\n\n\u003e *\"Publish my API at https://api.example.com/sentiment for $0.001 per call.\"*\n\n## Tools\n\n13 tools across 4 domains. Tools auto-register based on which env vars are set —\nthe agent never sees a tool it can't use.\n\n### Discovery — always available\n\n| Tool | Description |\n|------|-------------|\n| `gatefare.search_apis` | Full-text search the catalog with filters (price, category, sort) |\n| `gatefare.get_api` | Full details for one API by slug or `handle/urlName` |\n| `gatefare.list_categories` | All categories with API counts |\n| `gatefare.suggest` | Autocomplete suggestions for a query string |\n\n### Buyer — needs `WALLET_PRIVATE_KEY`\n\n| Tool | Description |\n|------|-------------|\n| `gatefare.call_api` | Make a paid call. Handles 402 → sign → retry automatically |\n| `gatefare.get_wallet_balance` | USDC + ETH on Base, plus remaining runtime budget |\n| `gatefare.estimate_cost` | Project total cost for N planned calls |\n\n### Publisher — needs `GATEFARE_PAT`\n\n| Tool | Description |\n|------|-------------|\n| `gatefare.register_api` | Publish a new paid API |\n| `gatefare.list_my_apis` | Your published APIs with stats |\n| `gatefare.update_api` | Edit metadata, price, target URL |\n| `gatefare.get_revenue` | Revenue time series + totals |\n| `gatefare.distribute` | Trigger on-chain `distribute()` payout (destructive) |\n\n### Safety — always available\n\n| Tool | Description |\n|------|-------------|\n| `gatefare.report_abuse` | Report a malicious / stolen API (DMCA, fraud, malware…) |\n\n## Configuration\n\n| Var | Default | Required for |\n|-----|---------|--------------|\n| `GATEFARE_BASE_URL` | `https://gatefare.io` | — (override for self-hosted) |\n| `WALLET_PRIVATE_KEY` | — | Any buyer tool |\n| `WALLET_BUDGET_USD` | unlimited | Optional spend cap |\n| `WALLET_NETWORK` | `eip155:8453` | `eip155:84532` for Sepolia testnet |\n| `GATEFARE_PAT` | — | Any publisher tool |\n| `LOG_LEVEL` | `info` | `debug` for verbose stderr |\n\n## Examples\n\n### Discover \u0026 buy in one breath (Claude Desktop)\n\n\u003e **You:** *Find me a sub-$0.001 weather API and call it for \"Tokyo\".*\n\u003e\n\u003e **Claude:** *Calling `gatefare.search_apis` with `max_price: 0.001`…*  \n\u003e           *Found `demo-weather` by @alice at $0.001/call.*  \n\u003e           *Calling `gatefare.call_api` with `slug: \"demo-weather\"`, `query: {city: \"Tokyo\"}`…*  \n\u003e           *Tokyo is 22°C, partly cloudy. Paid 0.001 USDC. Receipt: `settled-tx-0x9a…`*\n\n### Programmatic — Python agent\n\n```python\nfrom mcp import ClientSession, StdioServerParameters\nfrom mcp.client.stdio import stdio_client\n\nserver = StdioServerParameters(\n    command=\"npx\",\n    args=[\"-y\", \"@gatefare/mcp\"],\n    env={\"WALLET_PRIVATE_KEY\": \"0x...\", \"WALLET_BUDGET_USD\": \"1.00\"},\n)\n\nasync with stdio_client(server) as (r, w):\n    async with ClientSession(r, w) as s:\n        await s.initialize()\n        result = await s.call_tool(\n            \"gatefare.call_api\",\n            arguments={\"slug\": \"demo-weather\", \"query\": {\"city\": \"Tokyo\"}},\n        )\n        print(result.content[0].text)\n```\n\nSee [`examples/`](examples/) for runnable variants: Claude Desktop, Cursor, Python,\nTypeScript, and a pure-discovery walkthrough.\n\n### Not building an AI agent? Picking the right tool\n\nIf you want to **pay for x402 APIs from a backend** (no agent), use Coinbase's\nofficial x402 SDKs — `x402-python` (PyPI), `coinbase/x402/go`, `…/java`, or\n[`@x402/fetch`](https://www.npmjs.com/package/x402-fetch). They handle the\npayment flow; you don't need this MCP server.\n\nIf you want to **browse the Gatefare catalog** from any language, hit the\nREST API directly: [`gatefare.io/api/catalog`](https://gatefare.io/api/catalog)\n([OpenAPI 3.1 spec](https://gatefare.io/openapi.json)).\n\nFull breakdown of which tool fits which use case in\n[`docs/integrations.md`](docs/integrations.md).\n\n### Direct CLI (for debugging)\n\n```bash\n# Run the server in foreground; talks JSON-RPC over stdio.\nnpx -y @gatefare/mcp\n\n# In another terminal, send a frame:\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | \\\n  npx -y @gatefare/mcp\n```\n\n## Errors\n\nTool results include `isError: true` and a structured body\n`{ error: \u003ccode\u003e, message: \u003chuman\u003e, details?: \u003cany\u003e }`. Codes are stable —\nagents can switch on them for retry / surfacing logic.\n\n| Code | Meaning |\n|------|---------|\n| `INVALID_INPUT` | Input failed zod validation |\n| `WALLET_NOT_CONFIGURED` | Set `WALLET_PRIVATE_KEY` for buyer tools |\n| `PAT_NOT_CONFIGURED` | Set `GATEFARE_PAT` for publisher tools |\n| `BUDGET_EXHAUSTED` | Runtime budget cap hit |\n| `INSUFFICIENT_BALANCE` | Wallet doesn't have enough USDC |\n| `PRICE_TOO_HIGH` | Server's price exceeds your `max_price` |\n| `API_NOT_FOUND` | Slug doesn't exist or is suspended |\n| `UPSTREAM_ERROR` | Paid API returned non-2xx, or its 402 was malformed |\n| `RATE_LIMITED` | Gatefare rate-limited the request |\n| `NETWORK_ERROR` | Could not reach Gatefare |\n| `GATEFARE_API_ERROR` | Gatefare returned a 4xx / 5xx |\n\n## How it works (the 30-second version)\n\n1. The agent calls `gatefare.call_api { slug: \"demo-weather\", … }`.\n2. We `GET https://gatefare.io/p/demo-weather` (no payment yet).\n3. The Gatefare proxy returns **402 Payment Required** with `accepts: [{network, payTo, maxAmountRequired, …}]`.\n4. We sign an [EIP-3009 `transferWithAuthorization`](https://eips.ethereum.org/EIPS/eip-3009) for that exact amount and recipient on the configured network.\n5. We retry the request with the signed `X-Payment` header (base64-encoded JSON, x402 v2).\n6. Gatefare verifies the signature, settles the USDC transfer, and proxies the call to the upstream API.\n7. We hand the upstream response (and a payment receipt) back to the agent.\n\nThe signature is single-use, time-bounded, and never leaves your machine for any\npurpose other than this exact transfer to this exact `payTo`. The private key\nis never logged.\n\n## Security\n\n- **Non-custodial.** Private keys live in your env, signing happens locally,\n  no Gatefare service ever sees them.\n- **Network confusion-resistant.** A malicious gateway returning Sepolia-only\n  requirements to a mainnet user is rejected — we never sign for a chain\n  the user didn't configure.\n- **Cryptographically random nonces.** No `Date.now()`-based collisions.\n- **Validity window clamped to 1 hour** even if the server requests more.\n- **Strict input validation.** Slugs are `^[a-z0-9_-]+$` and URL-encoded;\n  no path traversal. `targetUrl` blocks `file://`, `localhost`, cloud\n  metadata IPs, `.local`, and `.internal` hosts at registration time.\n- **Secret hygiene.** Tests assert that the private key and PAT never\n  appear in stderr / stdout, ever.\n\n## Development\n\n```bash\ngit clone https://github.com/gatefareio/mcp-server.git\ncd mcp-server\nnpm install\nnpm run typecheck\nnpm test                  # 138 unit tests\nnpm run test:e2e          # 10 e2e tests against live gatefare.io (set GATEFARE_E2E=1)\nnpm run build\n```\n\nTo use a local checkout in your client config:\n\n```bash\nnpm link\n# in claude_desktop_config.json:\n#   \"command\": \"gatefare-mcp\"\n```\n\n### Architecture\n\n```\nsrc/\n├── index.ts        # entry — wires stdio transport\n├── server.ts       # McpServer instance + tool registration\n├── config.ts       # env parsing, capability detection\n├── client.ts       # REST client (wraps fetch)\n├── x402.ts         # 402 parsing + EIP-3009 signing\n├── types.ts        # shared types + GatefareError\n└── tools/\n    ├── discovery.ts   # search_apis, get_api, list_categories, suggest\n    ├── buyer.ts       # call_api, get_wallet_balance, estimate_cost\n    ├── publisher.ts   # register_api, list_my_apis, update_api, get_revenue, distribute\n    └── safety.ts      # report_abuse\n```\n\n### Test layout\n\n```\ntests/\n├── config.test.ts         # env parsing edges\n├── client.test.ts         # HTTP client error mapping\n├── x402.test.ts           # signing + parsing primitives\n├── x402-flow.test.ts      # full 402 → sign → retry handshake (mocked fetch)\n├── server.test.ts         # capability-driven tool registration\n├── init.test.ts           # subprocess: bootstrap, env crashes, secret leakage\n├── stdio-protocol.test.ts # stdout pollution + recovery from tool errors\n├── stability.test.ts      # 100 concurrent calls, memory baseline, ReDoS\n├── tools/\n│   ├── discovery.test.ts\n│   ├── buyer.test.ts\n│   ├── buyer-flow.test.ts\n│   ├── publisher.test.ts\n│   └── safety.test.ts\n└── integration/\n    └── e2e.test.ts        # real gatefare.io, gated by GATEFARE_E2E=1\n```\n\n## Contributing\n\nIssues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow,\nstyle guide, and how to add a new tool.\n\n## Related packages\n\nGatefare ships three first-party packages. They share the same x402\nprotocol and the same backend, so a project can mix them as needed:\n\n| Package | Where | When to use |\n|---|---|---|\n| [`@gatefare/mcp`](https://www.npmjs.com/package/@gatefare/mcp) (this one) | npm | Drop into Claude Desktop / Cursor / any MCP host to give the agent tools for catalog discovery + paid calls |\n| [`@gatefare/client`](https://www.npmjs.com/package/@gatefare/client) | npm | TypeScript / JavaScript agents that pay APIs in code, outside MCP |\n| [`gatefare`](https://pypi.org/project/gatefare/) | PyPI | Python agents (LangChain, LlamaIndex, etc.) |\n\n## License\n\n[MIT](LICENSE) © Gatefare\n\n## Links\n\n- 🌐 Marketplace: [gatefare.io](https://gatefare.io)\n- 📚 API docs: [gatefare.io/docs](https://gatefare.io/docs)\n- 🤖 LLM context (single file): [gatefare.io/llms-full.txt](https://gatefare.io/llms-full.txt)\n- 📐 OpenAPI spec: [gatefare.io/openapi.json](https://gatefare.io/openapi.json)\n- 🐦 Twitter: [@Gatefareio](https://twitter.com/Gatefareio)\n- 🔌 Model Context Protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io)\n- 💸 x402 standard: [x402.org](https://x402.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgatefareio%2Fmcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgatefareio%2Fmcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgatefareio%2Fmcp-server/lists"}