Gatefare — paid-API marketplace

@gatefare/mcp

为你的 AI Agent 提供一个钱包和一个市场。

@gatefare/mcp 是一个模型上下文协议服务，可将 Claude Desktop、Cursor 或任何兼容 MCP 的 Agent 连接到 Gatefare 的付费 HTTP API 目录。付款通过开放的 x402 标准 以 Base 上的 USDC 结算——无需 SaaS 密钥、订阅或托管。非托管：签名在本地完成；私钥永远不会离开你的设备。

┌─────────────┐                ┌──────────────┐                ┌─────────────────┐
│ Claude /    │   MCP stdio    │ @gatefare/mcp│  HTTP + x402   │ gatefare.io     │
│ Cursor /    │ ─────────────► │   (this repo)│ ─────────────► │ proxy +         │
│ your agent  │                │              │                │ catalog         │
└─────────────┘                └──────┬───────┘                └─────────────────┘
                                      │
                                      │ EIP-3009 sign
                                      ▼
                                ┌─────────────┐
                                │  Base USDC  │
                                └─────────────┘

快速开始

1. 添加到你的客户端

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "gatefare": {
      "command": "npx",
      "args": ["-y", "@gatefare/mcp"]
    }
  }
}

Cursor — ~/.cursor/mcp.json 或项目级 .cursor/mcp.json：

{
  "mcpServers": {
    "gatefare": {
      "command": "npx",
      "args": ["-y", "@gatefare/mcp"]
    }
  }
}

重启客户端。Agent 现在拥有 5 个只读工具——用于发现和安全保障。试试：

“搜索 Gatefare 上的天气 API。”

2. 添加钱包以进行付费调用

在相同配置中添加 env：

{
  "mcpServers": {
    "gatefare": {
      "command": "npx",
      "args": ["-y", "@gatefare/mcp"],
      "env": {
        "WALLET_PRIVATE_KEY": "0xYOUR_KEY",
        "WALLET_BUDGET_USD": "5.00"
      }
    }
  }
}

买家工具（call_api、get_wallet_balance、estimate_cost）现已可用。 WALLET_BUDGET_USD 上限是运行时安全保障——如需硬性上限，请只向钱包充值你愿意花费的金额。

“伦敦现在的天气怎么样？最多花费 $0.001。”

3. （可选）发布你自己的 API

在 gatefare.io/dashboard/tokens 获取 PAT 并添加：

"env": {
  "GATEFARE_PAT": "gfpat_..."
}

发布者工具（register_api、list_my_apis、update_api、get_revenue、 distribute）将会显示。

“以每次调用 $0.001 的价格，发布我位于 https://api.example.com/sentiment 的 API。”

工具

4 个领域共提供 13 个工具。工具会根据设置的环境变量自动注册——Agent 永远不会看到自己无法使用的工具。

发现 — 始终可用

工具	描述
gatefare.search_apis	使用筛选条件（价格、类别、排序）对目录进行全文搜索
gatefare.get_api	根据 slug 或 handle/urlName 获取某个 API 的完整详情
gatefare.list_categories	获取所有类别及其 API 数量
gatefare.suggest	根据查询字符串提供自动补全建议

买家 — 需要 WALLET_PRIVATE_KEY

工具	描述
gatefare.call_api	进行付费调用。自动处理 402 → 签名 → 重试
gatefare.get_wallet_balance	查询 Base 上的 USDC + ETH，以及剩余运行时预算
gatefare.estimate_cost	估算计划调用 N 次的总费用

发布者 — 需要 GATEFARE_PAT

工具	描述
gatefare.register_api	发布新的付费 API
gatefare.list_my_apis	查看你已发布的 API 及其统计信息
gatefare.update_api	编辑元数据、价格和目标 URL
gatefare.get_revenue	查看收入时间序列和总额
gatefare.distribute	触发链上 distribute() 付款（有破坏性）

安全 — 始终可用

工具	描述
gatefare.report_abuse	举报恶意或被盗用的 API（DMCA、欺诈、恶意软件……）

配置

变量	默认值	用途
GATEFARE_BASE_URL	https://gatefare.io	—（可自托管时用于覆盖）
WALLET_PRIVATE_KEY	—	任何买家工具
WALLET_BUDGET_USD	unlimited	可选的支出上限
WALLET_NETWORK	eip155:8453	Sepolia 测试网使用 eip155:84532
GATEFARE_PAT	—	任何发布者工具
LOG_LEVEL	info	debug 用于输出详细的 stderr 日志

示例

一次完成发现和购买（Claude Desktop）

你： 帮我找一个价格低于 $0.001 的天气 API，并查询“东京”的天气。

Claude： 正在调用 gatefare.search_apis，参数为 max_price: 0.001……
找到 @alice 提供的 demo-weather，价格为 $0.001/次调用。
正在调用 gatefare.call_api，参数为 slug: "demo-weather"、query: {city: "Tokyo"}……
东京气温为 22°C，局部多云。已支付 0.001 USDC。收据：settled-tx-0x9a…

以编程方式使用 — Python Agent

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server = StdioServerParameters(
    command="npx",
    args=["-y", "@gatefare/mcp"],
    env={"WALLET_PRIVATE_KEY": "0x...", "WALLET_BUDGET_USD": "1.00"},
)

async with stdio_client(server) as (r, w):
    async with ClientSession(r, w) as s:
        await s.initialize()
        result = await s.call_tool(
            "gatefare.call_api",
            arguments={"slug": "demo-weather", "query": {"city": "Tokyo"}},
        )
        print(result.content[0].text)

可运行的变体请参阅 examples/，包括 Claude Desktop、Cursor、Python、 TypeScript，以及纯发现流程的演示。

不在构建 AI Agent？选择合适的工具

如果你想通过后端为 x402 API 付款（不使用 Agent），请使用 Coinbase 官方的 x402 SDK——x402-python (PyPI)、coinbase/x402/go、…/java，或 @x402/fetch。这些 SDK 会处理 付款流程；你不需要此 MCP 服务。

如果你想用任何语言浏览 Gatefare 目录，可直接调用 REST API：gatefare.io/api/catalog (OpenAPI 3.1 规范)。

关于不同使用场景适用的工具，请参阅 docs/integrations.md 中的完整说明。

直接使用 CLI（用于调试）

# Run the server in foreground; talks JSON-RPC over stdio.
npx -y @gatefare/mcp

# In another terminal, send a frame:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  npx -y @gatefare/mcp

错误

工具结果包含 isError: true 和结构化内容 { error: <code>, message: <human>, details?: <any> }。错误代码稳定不变 — Agent 可据此执行重试或错误提示逻辑。

代码	含义
INVALID_INPUT	输入未通过 zod 验证
WALLET_NOT_CONFIGURED	为买家工具设置 WALLET_PRIVATE_KEY
PAT_NOT_CONFIGURED	为发布者工具设置 GATEFARE_PAT
BUDGET_EXHAUSTED	已达到运行时预算上限
INSUFFICIENT_BALANCE	钱包中的 USDC 不足
PRICE_TOO_HIGH	服务价格超过了你的 max_price
API_NOT_FOUND	Slug 不存在或已暂停
UPSTREAM_ERROR	付费 API 返回了非 2xx 响应，或其 402 响应格式错误
RATE_LIMITED	Gatefare 对请求进行了速率限制
NETWORK_ERROR	无法连接到 Gatefare
GATEFARE_API_ERROR	Gatefare 返回了 4xx / 5xx 响应

工作原理（30 秒版）

1. Agent 调用 gatefare.call_api { slug: "demo-weather", … }。
2. 我们执行 GET https://gatefare.io/p/demo-weather（此时尚未付款）。
3. Gatefare 代理返回 402 Payment Required，并附带 accepts: [{network, payTo, maxAmountRequired, …}]。
4. 我们在配置的网络上，为准确的金额和收款方签署 EIP-3009 transferWithAuthorization。
5. 我们使用签名后的 X-Payment 请求标头（经过 base64 编码的 JSON，x402 v2）重试请求。
6. Gatefare 验证签名、结算 USDC 转账，并将调用转发到上游 API。
7. 我们将上游响应（以及付款收据）返回给 Agent。

该签名只能使用一次、有时间限制，并且除用于向指定 payTo 执行此笔转账外， 绝不会离开你的设备。私钥绝不会被记录。

安全

• 非托管。 私钥保存在你的环境变量中，签名在本地进行， Gatefare 服务绝不会接触这些密钥。
• 可抵御网络混淆。 恶意网关向主网用户返回仅适用于 Sepolia 的 要求时，请求会被拒绝——我们绝不会为用户未配置的链签名。
• 使用密码学安全的随机数生成 nonce。 不会出现基于 Date.now() 的冲突。
• 有效期最长限制为 1 小时，即使服务端请求更长的有效期也不例外。
• 严格的输入验证。 Slug 必须符合 ^[a-z0-9_-]+$ 并进行 URL 编码； 不允许路径穿越。注册时，targetUrl 会屏蔽 file://、localhost、云 元数据 IP、.local 和 .internal 主机。
• 密钥卫生。 测试会断言私钥和 PAT 绝不会出现在 stderr / stdout 中。

开发

git clone https://github.com/gatefareio/mcp-server.git
cd mcp-server
npm install
npm run typecheck
npm test                  # 138 unit tests
npm run test:e2e          # 10 e2e tests against live gatefare.io (set GATEFARE_E2E=1)
npm run build

若要在客户端配置中使用本地检出版本：

npm link
# in claude_desktop_config.json:
#   "command": "gatefare-mcp"

架构

src/
├── index.ts        # entry — wires stdio transport
├── server.ts       # McpServer instance + tool registration
├── config.ts       # env parsing, capability detection
├── client.ts       # REST client (wraps fetch)
├── x402.ts         # 402 parsing + EIP-3009 signing
├── types.ts        # shared types + GatefareError
└── tools/
    ├── discovery.ts   # search_apis, get_api, list_categories, suggest
    ├── buyer.ts       # call_api, get_wallet_balance, estimate_cost
    ├── publisher.ts   # register_api, list_my_apis, update_api, get_revenue, distribute
    └── safety.ts      # report_abuse

测试布局

tests/
├── config.test.ts         # env parsing edges
├── client.test.ts         # HTTP client error mapping
├── x402.test.ts           # signing + parsing primitives
├── x402-flow.test.ts      # full 402 → sign → retry handshake (mocked fetch)
├── server.test.ts         # capability-driven tool registration
├── init.test.ts           # subprocess: bootstrap, env crashes, secret leakage
├── stdio-protocol.test.ts # stdout pollution + recovery from tool errors
├── stability.test.ts      # 100 concurrent calls, memory baseline, ReDoS
├── tools/
│   ├── discovery.test.ts
│   ├── buyer.test.ts
│   ├── buyer-flow.test.ts
│   ├── publisher.test.ts
│   └── safety.test.ts
└── integration/
    └── e2e.test.ts        # real gatefare.io, gated by GATEFARE_E2E=1

贡献

欢迎提交问题和 PR。有关工作流、风格指南以及如何添加新工具，请参阅 CONTRIBUTING.md。

相关软件包

Gatefare 提供三个第一方软件包。它们使用相同的 x402 协议和相同的后端，因此项目可以根据需要混合使用：

软件包	发布平台	使用场景
@gatefare/mcp（本软件包）	npm	接入 Claude Desktop / Cursor / 任意 MCP 宿主，为 Agent 提供用于目录发现和付费调用的工具
@gatefare/client	npm	在 MCP 之外通过代码为 API 付费的 TypeScript / JavaScript Agent
gatefare	PyPI	Python Agent（LangChain、LlamaIndex 等）

许可证

MIT © Gatefare

链接

• 🌐 市场：gatefare.io
• 📚 API 文档：gatefare.io/docs
• 🤖 LLM 上下文（单文件）：gatefare.io/llms-full.txt
• 📐 OpenAPI 规范：gatefare.io/openapi.json
• 🐦 Twitter：@Gatefareio
• 🔌 模型上下文协议：modelcontextprotocol.io
• 💸 x402 标准：x402.org