@gatefare/mcp

Dale a tu agente de IA una billetera y un mercado.

@gatefare/mcp es un servidor del Protocolo de Contexto de Modelo (MCP) que conecta Claude Desktop, Cursor o cualquier agente compatible con MCP al catálogo de APIs HTTP de pago de Gatefare. Los pagos se liquidan en USDC en Base mediante el estándar abierto x402: sin claves SaaS, sin suscripciones, sin depósito en garantía. Sin custodia: la firma se realiza localmente; la clave privada nunca abandona tu máquina.

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

Inicio rápido

1. Integración en tu cliente

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

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

Cursor — ~/.cursor/mcp.json o .cursor/mcp.json a nivel de proyecto:

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

Reinicia el cliente. El agente ahora tiene 5 herramientas de solo lectura: descubrimiento + seguridad. Prueba:

"Busca APIs de clima en Gatefare."

2. Añade una billetera para realizar llamadas de pago

Añade env a la misma configuración:

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

Las herramientas de comprador (call_api, get_wallet_balance, estimate_cost) estarán disponibles. El límite WALLET_BUDGET_USD es una red de seguridad en tiempo de ejecución; para un límite estricto, financia la billetera solo con lo que estés dispuesto a gastar.

"¿Qué clima hace en Londres ahora mismo? Gasta hasta $0.001."

3. (Opcional) Publica tus propias APIs

Obtén un PAT en gatefare.io/dashboard/tokens y añade:

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

Aparecerán las herramientas de editor (register_api, list_my_apis, update_api, get_revenue, distribute).

"Publica mi API en https://api.example.com/sentiment por $0.001 por llamada."

Herramientas

13 herramientas en 4 dominios. Las herramientas se autorregistran según las variables de entorno configuradas; el agente nunca ve una herramienta que no puede usar.

Descubrimiento — siempre disponible

Comprador — requiere WALLET_PRIVATE_KEY

Editor — requiere GATEFARE_PAT

Seguridad — siempre disponible

Configuración

Ejemplos

Descubrir y comprar de una vez (Claude Desktop)

Tú: Encuéntrame una API de clima de menos de $0.001 y llámala para "Tokio".

Claude: Llamando a gatefare.search_apis con max_price: 0.001… Encontré demo-weather de @alice a $0.001/llamada. Llamando a gatefare.call_api con slug: "demo-weather", query: {city: "Tokio"}… Tokio está a 22°C, parcialmente nublado. Pagado 0.001 USDC. Recibo: settled-tx-0x9a…

Programático — Agente 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)

Consulta examples/ para ver variantes ejecutables: Claude Desktop, Cursor, Python, TypeScript y un tutorial de descubrimiento puro.

¿No estás creando un agente de IA? Eligiendo la herramienta correcta

Si quieres pagar por APIs x402 desde un backend (sin agente), usa los SDKs oficiales de x402 de Coinbase: x402-python (PyPI), coinbase/x402/go, …/java o @x402/fetch. Ellos manejan el flujo de pago; no necesitas este servidor MCP.

Si quieres navegar por el catálogo de Gatefare desde cualquier lenguaje, accede a la API REST directamente: gatefare.io/api/catalog (especificación OpenAPI 3.1).

Desglose completo de qué herramienta se ajusta a cada caso de uso en docs/integrations.md.

CLI directo (para depuración)

# 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

Errores

Los resultados de las herramientas incluyen isError: true y un cuerpo estructurado { error: <code>, message: <human>, details?: <any> }. Los códigos son estables; los agentes pueden usarlos para lógica de reintento o visualización.

Cómo funciona (versión de 30 segundos)

1. El agente llama a gatefare.call_api { slug: "demo-weather", … }.

2. Hacemos GET https://gatefare.io/p/demo-weather (aún sin pago).

3. El proxy de Gatefare devuelve 402 Payment Required con accepts: [{network, payTo, maxAmountRequired, …}].

4. Firmamos una EIP-3009 transferWithAuthorization por esa cantidad exacta y destinatario en la red configurada.

5. Reintentamos la solicitud con el encabezado X-Payment firmado (JSON codificado en base64, x402 v2).

6. Gatefare verifica la firma, liquida la transferencia USDC y hace proxy de la llamada a la API upstream.

7. Devolvemos la respuesta upstream (y un recibo de pago) al agente.

La firma es de un solo uso, limitada en tiempo y nunca abandona tu máquina para ningún propósito que no sea esta transferencia exacta a este payTo exacto. La clave privada nunca se registra.

Seguridad

• Sin custodia. Las claves privadas viven en tu entorno, la firma ocurre localmente, ningún servicio de Gatefare las ve nunca.

• Resistente a la confusión de red. Se rechaza cualquier puerta de enlace maliciosa que devuelva requisitos exclusivos de Sepolia a un usuario de la red principal; nunca firmamos para una cadena que el usuario no configuró.

• Nonces criptográficamente aleatorios. Sin colisiones basadas en Date.now().

• Ventana de validez limitada a 1 hora incluso si el servidor solicita más.

• Validación de entrada estricta. Los slugs son ^[a-z0-9_-]+$ y están codificados en URL; no hay recorrido de ruta. targetUrl bloquea file://, localhost, IPs de metadatos en la nube, .local y hosts .internal en el momento del registro.

• Higiene de secretos. Las pruebas aseguran que la clave privada y el PAT nunca aparezcan en stderr / stdout, nunca.

Desarrollo

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

Para usar una copia local en la configuración de tu cliente:

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

Arquitectura

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

Diseño de pruebas

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

Contribución

Las incidencias y PRs son bienvenidos. Consulta CONTRIBUTING.md para el flujo de trabajo, la guía de estilo y cómo añadir una nueva herramienta.

Licencia

MIT © Gatefare

Enlaces

• 🌐 Mercado: gatefare.io

• 📚 Documentación de API: gatefare.io/docs

• 🤖 Contexto LLM (archivo único): gatefare.io/llms-full.txt

• 📐 Especificación OpenAPI: gatefare.io/openapi.json

• 🐦 Twitter: @Gatefareio

• 🔌 Protocolo de Contexto de Modelo: modelcontextprotocol.io

• 💸 Estándar x402: x402.org