@gatefare/mcp

Дайте своему ИИ-агенту кошелек и доступ к маркетплейсу.

@gatefare/mcp — это сервер протокола Model Context Protocol (MCP), который подключает Claude Desktop, Cursor или любого другого агента, совместимого с MCP, к каталогу платных HTTP API Gatefare. Платежи осуществляются в USDC в сети Base через открытый стандарт x402 — без 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"]
    }
  }
}

Перезапустите клиент. Теперь у агента есть 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

Получите PAT на gatefare.io/dashboard/tokens и добавьте:

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

Появятся инструменты издателя (register_api, list_my_apis, update_api, get_revenue, distribute).

"Опубликуй мой API по адресу https://api.example.com/sentiment за $0.001 за вызов."

Инструменты

13 инструментов в 4 доменах. Инструменты автоматически регистрируются в зависимости от того, какие переменные окружения установлены — агент никогда не увидит инструмент, который не может использовать.

Поиск — всегда доступно

Покупатель — требуется WALLET_PRIVATE_KEY

Издатель — требуется GATEFARE_PAT

Безопасность — всегда доступно

Конфигурация

Примеры

Поиск и покупка за один раз (Claude Desktop)

Вы: Найди мне API погоды дешевле $0.001 и вызови его для "Токио".

Claude: Вызываю gatefare.search_apis с max_price: 0.001… Найден demo-weather от @alice по цене $0.001/вызов. Вызываю gatefare.call_api с slug: "demo-weather", query: {city: "Токио"}… В Токио 22°C, переменная облачность. Оплачено 0.001 USDC. Квитанция: settled-tx-0x9a…

Программный доступ — Python-агент

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 и пошаговое руководство по поиску.

Не создаете ИИ-агента? Выбор правильного инструмента

Если вы хотите оплачивать API стандарта x402 из бэкенда (без агента), используйте официальные SDK x402 от Coinbase — x402-python (PyPI), coinbase/x402/go, …/java или @x402/fetch. Они обрабатывают процесс оплаты; этот 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> }. Коды стабильны — агенты могут использовать их для логики повторных попыток или отображения информации.

Как это работает (кратко)

1. Агент вызывает 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 (JSON в base64, x402 v2).

6. Gatefare проверяет подпись, проводит перевод USDC и проксирует вызов к целевому API.

7. Мы передаем ответ (и квитанцию об оплате) обратно агенту.

Подпись одноразовая, ограничена по времени и никогда не покидает ваш компьютер для любых целей, кроме этого конкретного перевода этому конкретному payTo. Закрытый ключ никогда не логируется.

Безопасность

• Без кастодиального хранения. Закрытые ключи находятся в вашем окружении, подписание происходит локально, ни один сервис Gatefare их не видит.

• Устойчивость к путанице сетей. Запросы от вредоносного шлюза, требующего Sepolia для пользователя основной сети, отклоняются — мы никогда не подписываем транзакции для сети, которую пользователь не настраивал.

• Криптографически случайные нонсы. Никаких коллизий на основе Date.now().

• Окно валидности ограничено 1 часом, даже если сервер запрашивает больше.

• Строгая валидация ввода. Слаги имеют вид ^[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 для ознакомления с рабочим процессом, руководством по стилю и тем, как добавить новый инструмент.

Лицензия

MIT © Gatefare

Ссылки

• 🌐 Маркетплейс: gatefare.io

• 📚 Документация API: gatefare.io/docs

• 🤖 Контекст для LLM (один файл): gatefare.io/llms-full.txt

• 📐 Спецификация OpenAPI: gatefare.io/openapi.json

• 🐦 Twitter: @Gatefareio

• 🔌 Model Context Protocol: modelcontextprotocol.io

• 💸 Стандарт x402: x402.org