MCPay

MCPay se sitúa entre un agente de IA y un servidor MCP. El agente recibe un token de gasto de corta duración vinculado a un único servidor, una lista de acciones fija, precios exactos, un presupuesto, una hora de expiración y un rango de nonces. La pasarela verifica esa política, reclama el nonce de forma atómica, llama a la herramienta ascendente y luego registra el uso de respuestas 2xx entregadas correctamente en un outbox duradero.

Sin suscripción por herramienta. Sin clave de API del creador dentro del agente. Sin dinero en coma flotante.

Estado de la beta: el repositorio ejecuta una beta cerrada sin dinero real. Las recargas de cartera son créditos de prueba en el libro mayor; los depósitos de Stripe, los pagos a creadores, KYC/AML, las disputas y los flujos de impuestos aún no están incluidos.

1. El agente crea una sesión de gasto respaldada por un saldo de cartera reservado.

2. MCPay firma el servidor exacto, los precios de las acciones, el presupuesto, la expiración y el rango de nonces.

3. La pasarela verifica el token y reclama el nonce en PostgreSQL antes del envío.

4. Una respuesta 2xx entregada entra en el outbox local de bbolt y se liquida de forma asíncrona.

El repositorio incluye una API en Go, una pasarela, un trabajador de liquidación, migraciones de PostgreSQL, un panel de creadores, SDK de JavaScript y Python, pruebas de navegador y una pila beta de Docker Compose. Los depósitos y pagos reales permanecen deshabilitados deliberadamente.

Recorrido por el producto

El plano de control muestra el presupuesto reservado del agente, los ingresos del creador, el volumen de llamadas de pago, la latencia de autorización local y la actividad de liquidación reciente.

Las capturas de pantalla usan un conjunto de datos de documentación fijo. Las cifras no son métricas de producción.

Related MCP server: MCP Gateway

Por qué existe MCPay

Un agente que llama a diez herramientas de pago no debería necesitar diez suscripciones, diez SDK de facturación y diez secretos de larga duración. Un creador no debería tener que escribir lógica de reserva, protección contra repetición, comprobaciones de precios, almacenamiento de recibos y trabajadores de liquidación antes de cobrar cinco centavos por web_search.

MCPay hace explícito el contrato de gasto antes de la ejecución:

Si el reclamo no coincide con la sesión activa, la pasarela se detiene antes de que el servidor ascendente vea la solicitud.

Cómo se compara

El checkout es la parte fácil. MCPay gestiona la autorización limitada, la supresión de duplicados entre hosts, los precios inmutables, el orden de revocación, la entrega duradera del uso aceptado y la liquidación segura frente a reintentos.

Ruta de la solicitud

sequenceDiagram
    participant A as Agent
    participant C as MCPay API
    participant G as MCPay Gateway
    participant P as PostgreSQL
    participant T as MCP Tool
    participant W as Settlement Worker

    A->>C: Create spend session
    C->>P: Reserve budget and store price snapshot
    C-->>A: Ed25519-signed spend token
    A->>G: tools/call + token + nonce
    G->>G: Verify issuer, server, action, price, expiry
    G->>P: Atomic nonce claim
    P-->>G: Active and unique
    G->>P: Mark nonce dispatched
    G->>T: Execute tool
    T-->>G: Result
    G-->>A: Result
    G->>G: Persist delivered 2xx usage in bbolt outbox
    G->>C: Upload usage batch
    C->>P: Insert idempotent usage record
    W->>P: Settle creator credit

La llamada al plano de control ocurre antes del envío porque la protección contra repetición solo sin conexión no puede coordinar dos máquinas de pasarela ni detener una sesión revocada. Las comprobaciones de firma aún se realizan localmente, por lo que los tokens malformados o fuera de alcance nunca llegan al reclamo de la base de datos.

Modelo de seguridad

MCPay no llama "cifrado" a un JWT firmado. No lo está. Los tokens de gasto llevan reclamaciones legibles y usan firmas Ed25519 para que una pasarela pueda detectar cualquier modificación sin tener la clave de firma.

Qué significa el cifrado en reposo aquí

MCPay no añade cifrado de campos a nivel de aplicación a las filas del libro mayor. Las credenciales de PostgreSQL, las claves de firma, los secretos de pasarela y las copias de seguridad pertenecen a tu gestor de secretos y a tu almacenamiento cifrado; PostgreSQL gestionado o volúmenes de host cifrados deberían proteger los archivos de la base de datos en reposo. Esa distinción importa porque afirmar que "todo está cifrado" ocultaría el límite de confianza real.

Para un despliegue beta, mantén PostgreSQL y el trabajador en una red privada, termina el TLS público en Caddy, monta los secretos en tiempo de ejecución, haz copias de seguridad antes de las migraciones y nunca confirmes deploy/.env.beta.

Ejecútalo localmente

Requisitos: Docker Engine con Compose v2, Go 1.25+ para la generación de claves y 4 GB de memoria disponible. Node.js 24 se ejecuta dentro del contenedor de compilación del panel.

cp deploy/.env.beta.example deploy/.env.beta
go run ./cmd/mcpay-keygen

Pega los valores Ed25519 generados en deploy/.env.beta, reemplaza cada valor replace-* y luego inicia la pila:

docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml config
docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml build
docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml up -d
docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml ps

Abre http://localhost:8080. La pila de compose inicia PostgreSQL, migraciones, API, trabajador, panel, Caddy y TLS interno. Las recargas de prueba siguen siendo créditos virtuales.

Comprueba la pila en ejecución:

MCPAY_BETA_URL=http://localhost:8080 ./scripts/verify-central-beta.sh

PowerShell:

./scripts/verify-central-beta.ps1 -BaseUrl http://localhost:8080

Las notas de despliegue, las copias de seguridad, el DNS y la opción de Vercel/Supabase están en docs/central-beta-runbook.md y docs/beta-deployment.md.

Conecta un servidor MCP

Crea un servidor y una acción en Creator Studio, emite su credencial de pasarela limitada al servidor y luego ejecuta la pasarela desde el repositorio junto al proceso MCP:

go run ./cmd/mcpay-gateway \
  --target https://your-mcp-server.example \
  --mcp-path /mcp \
  --server-id srv_example \
  --environment beta \
  --token-issuer mcpay.beta \
  --public-key "$MCPAY_PUBLIC_KEY" \
  --control-plane-api https://api.example/v1/gateway/servers/srv_example \
  --nonce-claim-api https://api.example/v1/gateway/nonces/claim \
  --usage-api https://api.example/v1/usage-records \
  --usage-api-token "$MCPAY_GATEWAY_API_TOKEN" \
  --state-file ./mcpay-gateway.db

Las solicitudes de pago llevan dos cabeceras:

Authorization: Bearer <spend-token>
X-MCPay-Nonce: <nonce-within-the-signed-range>

La pasarela elimina ambas cabeceras antes de reenviar la solicitud al servidor ascendente.

Conecta un agente

MCPayAgentClient crea sesiones de corta duración e inyecta cabeceras de pago solo en orígenes de pasarela HTTPS de la lista blanca:

import {
  FileAgentSessionCreationStore,
  MCPayAgentClient,
} from "@mcpay/sdk-js";

const paid = new MCPayAgentClient({
  apiBaseUrl: "https://pay.example.com/api/mcpay",
  accessToken: process.env.MCPAY_ACCESS_TOKEN!,
  walletId: process.env.MCPAY_WALLET_ID!,
  serverId: process.env.MCPAY_SERVER_ID!,
  reservedBudget: 50,
  gatewayOrigins: ["https://tools.example.com"],
  sessionCreationStore: new FileAgentSessionCreationStore(
    "./mcpay-agent-sessions.json",
  ),
});

const response = await paid.fetch("https://tools.example.com/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "web_search",
      arguments: { query: "payment rails for MCP" },
    },
  }),
});

La inicialización y el descubrimiento de herramientas pasan sin cabeceras de gasto. La creación de sesiones usa una clave de idempotencia, por lo que una respuesta perdida no reserva el presupuesto dos veces.

Envoltorios directos del SDK

Existen wrappers de JavaScript y Python para desarrollo e integraciones privadas. El modo de producción rechaza el uso volátil; la puerta de enlace duradera sigue siendo la ruta de despliegue recomendada porque conserva el estado de nonce y uso entre reinicios del proceso.

import { MCPayClient } from "@mcpay/sdk-js";

const mcpay = new MCPayClient({
  publicKey: process.env.MCPAY_PUBLIC_KEY!,
  issuer: process.env.MCPAY_TOKEN_ISSUER!,
  serverId: process.env.MCPAY_SERVER_ID!,
  environment: "development",
  allowVolatileUsage: true,
});

export const paidSearch = mcpay.tool({
  name: "web_search",
  priceMinor: 5,
  handler: async (query: string) => search(query),
});

import os

from mcpay import MCPayClient

mcpay = MCPayClient(
    public_key=os.environ["MCPAY_PUBLIC_KEY"],
    issuer=os.environ["MCPAY_TOKEN_ISSUER"],
    server_id=os.environ["MCPAY_SERVER_ID"],
    environment="development",
    allow_volatile_usage=True,
)

@mcpay.tool(name="web_search", price_minor=5)
async def search(query: str):
    return await run_search(query)

Verificación

La rama principal comprueba Go, la integración con PostgreSQL, las migraciones, ambos SDK, las pruebas de navegador, las compilaciones de paquetes, las auditorías de dependencias y la configuración de Docker Compose.

go test ./...
go test -race ./...
go vet ./...
go build ./cmd/...
npm ci
npm audit --audit-level=high
npm run build
npm run test
python -m pip install build
python -m build packages/sdk-python
python -m unittest discover -s packages/sdk-python/tests

Para las pruebas de PostgreSQL, apunta MCPAY_TEST_DATABASE_URL a una base de datos migrada desechable. Las pruebas truncan las tablas de la aplicación; nunca uses una base de datos de producción.

Ejecuta el benchmark de autorización de bucle de retorno con:

go run ./cmd/mcpay-benchmark --samples 1000 --warmup 100

Informa de p50/p95/p99 sin procesar, del SDK local y de la puerta de enlace en tu máquina. El benchmark excluye la configuración de sesión, las escrituras en el libro mayor central y la carga asíncrona de uso, por lo que no es un SLA de producción.

Qué se incluye hoy

MCPay está listo para una beta controlada con créditos de prueba. No está listo para custodiar fondos de clientes.

Mapa del repositorio

Licencia

MCPay utiliza la Business Source License 1.1. BSL no es una licencia de código abierto aprobada por OSI, pero da a todos acceso al código fuente y permite la copia, modificación, redistribución y uso no productivo.

La Concesión de Uso Adicional de MCPay permite el uso productivo interno cuando el usuario u organización no supera los 100.000 USD de ingresos brutos agregados durante los 12 meses anteriores. No permite un servicio MCPay alojado, gestionado, integrado o de marca blanca para terceros. El uso productivo fuera de esa concesión requiere una licencia comercial; abre un issue en el repositorio oficial para solicitar condiciones comerciales.

El 13 de agosto de 2030, esta versión pasa a la Apache License 2.0. BSL también aplica su Change License de código abierto en el cuarto aniversario de la primera distribución pública BSL de una versión si esa fecha llega antes.

Lee LICENSE para conocer los términos vinculantes. El panel se distribuye por separado bajo la licencia MIT en apps/dashboard/LICENSE, incluida la atribución a su autor original y las modificaciones de MCPay. Haz que un asesor legal revise los parámetros de BSL antes de un lanzamiento con dinero real o una diligencia de recaudación de fondos.

La investigación de seguridad es bienvenida. El acceso al código fuente hace posible la revisión; no demuestra la ausencia de vulnerabilidades, y BSL proporciona el software sin garantía de seguridad.