@gatefare/mcp

Geben Sie Ihrem KI-Agenten eine Wallet und einen Marktplatz.

@gatefare/mcp ist ein Model Context Protocol-Server, der Claude Desktop, Cursor oder jeden anderen MCP-kompatiblen Agenten mit dem Gatefare-Katalog kostenpflichtiger HTTP-APIs verbindet. Zahlungen werden als USDC auf Base über den offenen x402-Standard abgewickelt – keine SaaS-Schlüssel, keine Abonnements, keine Treuhandkonten. Nicht-verwahrt (non-custodial): Das Signieren erfolgt lokal; der private Schlüssel verlässt niemals Ihren Rechner.

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

Schnelleinstieg

1. In Ihren Client einbinden

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor — ~/.cursor/mcp.json oder .cursor/mcp.json auf Projektebene:

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

Starten Sie den Client neu. Der Agent verfügt nun über 5 schreibgeschützte Tools – für Entdeckung + Sicherheit. Versuchen Sie:

"Suche auf Gatefare nach Wetter-APIs."

2. Wallet hinzufügen, um kostenpflichtige Aufrufe zu tätigen

Fügen Sie env zur gleichen Konfiguration hinzu:

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

Käufer-Tools (call_api, get_wallet_balance, estimate_cost) werden verfügbar. Das WALLET_BUDGET_USD-Limit ist ein Sicherheitsnetz zur Laufzeit – für ein hartes Limit laden Sie die Wallet nur mit dem Betrag auf, den Sie ausgeben möchten.

"Wie ist das Wetter in London gerade? Gib bis zu $0.001 aus."

3. (Optional) Eigene APIs veröffentlichen

Holen Sie sich ein PAT unter gatefare.io/dashboard/tokens und fügen Sie hinzu:

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

Publisher-Tools (register_api, list_my_apis, update_api, get_revenue, distribute) erscheinen.

"Veröffentliche meine API unter https://api.example.com/sentiment für $0.001 pro Aufruf."

Tools

13 Tools in 4 Bereichen. Tools registrieren sich automatisch basierend darauf, welche Umgebungsvariablen gesetzt sind – der Agent sieht niemals ein Tool, das er nicht verwenden kann.

Entdeckung – immer verfügbar

Käufer – benötigt WALLET_PRIVATE_KEY

Publisher – benötigt GATEFARE_PAT

Sicherheit – immer verfügbar

Konfiguration

Beispiele

Entdecken & Kaufen in einem Schritt (Claude Desktop)

Sie: Finde eine Wetter-API unter $0.001 und rufe sie für "Tokio" auf.

Claude: Rufe gatefare.search_apis mit max_price: 0.001 auf… Gefunden demo-weather von @alice für $0.001/Aufruf. Rufe gatefare.call_api mit slug: "demo-weather", query: {city: "Tokio"} auf… Tokio hat 22°C, teilweise bewölkt. 0.001 USDC bezahlt. Quittung: settled-tx-0x9a…

Programmatisch – 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)

Siehe examples/ für ausführbare Varianten: Claude Desktop, Cursor, Python, TypeScript und eine reine Entdeckungs-Anleitung.

Sie bauen keinen KI-Agenten? Das richtige Tool wählen

Wenn Sie für x402-APIs von einem Backend aus bezahlen möchten (kein Agent), verwenden Sie die offiziellen x402-SDKs von Coinbase — x402-python (PyPI), coinbase/x402/go, …/java oder @x402/fetch. Diese übernehmen den Zahlungsfluss; Sie benötigen diesen MCP-Server nicht.

Wenn Sie den Gatefare-Katalog aus einer beliebigen Sprache durchsuchen möchten, greifen Sie direkt auf die REST-API zu: gatefare.io/api/catalog (OpenAPI 3.1 Spezifikation).

Vollständige Aufschlüsselung, welches Tool für welchen Anwendungsfall geeignet ist, finden Sie in docs/integrations.md.

Direktes CLI (zum Debuggen)

# 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

Fehler

Tool-Ergebnisse enthalten isError: true und einen strukturierten Body { error: <code>, message: <human>, details?: <any> }. Die Codes sind stabil — Agenten können darauf reagieren, um Wiederholungsversuche oder Anzeige-Logik zu steuern.

Funktionsweise (die 30-Sekunden-Version)

1. Der Agent ruft gatefare.call_api { slug: "demo-weather", … } auf.

2. Wir führen GET https://gatefare.io/p/demo-weather aus (noch keine Zahlung).

3. Der Gatefare-Proxy gibt 402 Payment Required mit accepts: [{network, payTo, maxAmountRequired, …}] zurück.

4. Wir signieren eine EIP-3009 transferWithAuthorization für den exakten Betrag und Empfänger im konfigurierten Netzwerk.

5. Wir wiederholen die Anfrage mit dem signierten X-Payment-Header (base64-kodiertes JSON, x402 v2).

6. Gatefare verifiziert die Signatur, wickelt die USDC-Überweisung ab und leitet den Aufruf an die Upstream-API weiter.

7. Wir geben die Upstream-Antwort (und eine Zahlungsquittung) an den Agenten zurück.

Die Signatur ist einmalig verwendbar, zeitlich begrenzt und verlässt Ihren Rechner niemals für einen anderen Zweck als diese exakte Überweisung an diesen exakten payTo. Der private Schlüssel wird niemals protokolliert.

Sicherheit

• Nicht-verwahrt (Non-custodial). Private Schlüssel liegen in Ihrer Umgebung, das Signieren erfolgt lokal, kein Gatefare-Dienst sieht sie jemals.

• Resistent gegen Netzwerkverwechslungen. Ein bösartiges Gateway, das Sepolia-Anforderungen an einen Mainnet-Benutzer zurückgibt, wird abgelehnt — wir signieren niemals für eine Chain, die der Benutzer nicht konfiguriert hat.

• Kryptografisch zufällige Nonces. Keine Kollisionen basierend auf Date.now().

• Gültigkeitsfenster auf 1 Stunde begrenzt, selbst wenn der Server mehr anfordert.

• Strenge Eingabevalidierung. Slugs sind ^[a-z0-9_-]+$ und URL-kodiert; kein Pfad-Traversal. targetUrl blockiert file://, localhost, Cloud-Metadaten-IPs, .local und .internal-Hosts zum Zeitpunkt der Registrierung.

• Geheimnis-Hygiene. Tests stellen sicher, dass der private Schlüssel und das PAT niemals in stderr / stdout erscheinen.

Entwicklung

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

Um einen lokalen Checkout in Ihrer Client-Konfiguration zu verwenden:

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

Architektur

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

Test-Layout

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

Mitwirken

Issues und PRs sind willkommen. Siehe CONTRIBUTING.md für den Workflow, den Styleguide und wie man ein neues Tool hinzufügt.

Lizenz

MIT © Gatefare

Links

• 🌐 Marktplatz: gatefare.io

• 📚 API-Dokumentation: gatefare.io/docs

• 🤖 LLM-Kontext (einzelne Datei): gatefare.io/llms-full.txt

• 📐 OpenAPI-Spezifikation: gatefare.io/openapi.json

• 🐦 Twitter: @Gatefareio

• 🔌 Model Context Protocol: modelcontextprotocol.io

• 💸 x402-Standard: x402.org