DePix App Gateway

Pasarela de pagos Pix no custodial en Liquid Network. Un agente de IA crea checkouts/productos, lee el estado de las transacciones y gestiona tickets de soporte — 22 herramientas. No custodial: sin fondos, sin claves retenidas.

GitHubPrueba este MCPPatrocinado

Documentación

depix-mcp

El servidor MCP (Model Context Protocol) para DePix App — la interfaz orientada a agentes del gateway de pagos Pix↔DePix no custodial y de una billetera Liquid no custodial.

Un MCP, dos niveles de acceso. Mismo paquete, misma entrada de registro; lo que funciona depende solo de si la instancia en ejecución tiene una semilla:

	Nivel 1 — alojado	Nivel 2 — local
Cómo	`https://mcp.depixapp.com/mcp` (HTTP transmisible)	`npx -y @depixapp/mcp` (stdio)
Se ejecuta en	los servidores de DePix App	tu propia máquina
Herramientas	22 — recibir Pix, lecturas de estado, soporte	49 — las 22 más 27 `wallet_*`
Semilla	ninguna, nunca	la tuya, nunca sale de la máquina
Instalación	cero (claude.ai, ChatGPT)	Node.js ≥ 22.4

La custodia la decide quién tiene la semilla, no el transporte. Cada gasto materializa un firmante en proceso, y no hay ruta de firma remota — por lo que DePix App no puede alojar herramientas de billetera funcionales sin volverse custodial, y no lo hace. Eso es física, no un nivel de producto.

Qué es (y qué no es)

Ambos niveles:

Un cliente puro de la API pública de DePix (https://api.depixapp.com/api/*) para las 22 herramientas de gateway. No tiene credenciales críticas — sin token de Eulen, sin base de datos, sin HMAC de webhook. Tu clave sk_ se pasa tal cual a la API en cada llamada y vive solo en memoria para esa solicitud.
La misma puerta que todos. Sin ruta privilegiada: la misma autenticación, alcances y límites de tasa que cualquier agente externo.

Nivel 1 (mcp.depixapp.com) solamente: nunca firma, nunca tiene fondos, nunca almacena tu clave. No tiene código de billetera en absoluto — el motor de billetera no está simplemente deshabilitado allí, está estructuralmente ausente del grafo de importación de esa implementación, y una guardia de CI (npm run guard:hosted) hace fallar la compilación si eso alguna vez cambia.

Nivel 2 (npx) solamente: las 27 herramientas wallet_* tienen, envían, convierten y pagan — firmando localmente, dentro de tu propio proceso, bajo salvaguardas (topes de BRL por transacción y móviles de 24 horas, lista blanca opcional) que ninguna llamada a herramienta puede elevar. No hay herramienta que exporte la semilla, edite salvaguardas o pague un QR de checkout de comerciante.

Relacionado — `@depixapp/sdk`

El motor de billetera comenzó como el @depixapp/sdk independiente (aún publicado, aún compatible para uso programático en tu propio código Node). Si lo que quieres es un agente con una billetera, quieres este paquete: @depixapp/mcp ahora integra ese motor y lo expone a través de MCP, así que no hay que escribir nada.

Inicio rápido 1 — Conectar Claude Code (remoto, HTTP)

Pasa tu clave de API de DePix como encabezado Bearer. Comienza siempre con una clave de sandbox.

claude mcp add --transport http depix https://mcp.depixapp.com/mcp \
  --header "Authorization: Bearer sk_test_YOUR_KEY"

Luego prueba la conexión pidiendo a Claude que ejecute get_account. Debería devolver tu comerciante con is_live: false (sandbox).

Cursor — agrega a ~/.cursor/mcp.json (o a un .cursor/mcp.json de proyecto):

{
  "mcpServers": {
    "depix": {
      "url": "https://mcp.depixapp.com/mcp",
      "headers": { "Authorization": "Bearer sk_test_YOUR_KEY" }
    }
  }
}

O usa el enlace profundo de un clic. El marcador de posición de la clave vive DENTRO del valor base64 config=, así que recodifícalo con tu clave real primero:

node -e 'const cfg={url:"https://mcp.depixapp.com/mcp",headers:{Authorization:"Bearer sk_test_YOUR_KEY"}};console.log(Buffer.from(JSON.stringify(cfg)).toString("base64"))'

cursor://anysphere.cursor-deeplink/mcp/install?name=depix&config=<base64 from the command above>

La interfaz web de claude.ai solo admite OAuth en conectores personalizados (sin encabezado personalizado). Este servidor es un Servidor de Recursos OAuth 2.1 (WorkOS AuthKit): el conector web te inicia sesión, y la sesión reenvía tu inicio de sesión verificado a la API como portador. Para operar, primero debes vincular ese inicio de sesión a tu cuenta de DePix (panel → configuración del conector); hasta entonces las herramientas devuelven un mensaje tipado "aún no vinculado". Las sesiones OAuth son solo de lectura + comerciante y nunca pueden mover dinero (wallet_write) — usa una clave sk_ para retiros. Toda la superficie OAuth está controlada por una característica (AUTHKIT_DOMAIN): con ella sin configurar, solo las rutas de encabezado/stdio sk_ anteriores están activas. Los clientes de terminal siguen usando claves sk_.

Inicio rápido 2 — stdio local, 49 herramientas (Claude Desktop / Claude Code / Cursor)

Requiere Node.js ≥ 22.4. El único paquete npm oficial es @depixapp/mcp — el alcance @depixapp es propiedad de la organización; no instales ningún paquete sin alcance con nombre similar. Los secretos provienen del entorno, nunca de una bandera.

2a. Solo gateway (sin billetera)

Exactamente las 22 herramientas del nivel 1, ejecutándose localmente:

{
  "mcpServers": {
    "depix": {
      "command": "npx",
      "args": ["-y", "@depixapp/mcp"],
      "env": { "DEPIX_API_KEY": "sk_test_YOUR_KEY" }
    }
  }
}

Las 49 herramientas siguen listadas — las 27 wallet_* responden con un error tipado wallet_not_configured que le dice al agente que te pida ejecutar init. Eso es deliberado: los hosts de MCP capturan la lista de herramientas cuando se conectan, así que un catálogo que creciera después significaría "reinicia tu cliente".

2b. Primera ejecución — crear la billetera

init es una ceremonia humana en una terminal, nunca una herramienta MCP. Imprime tu respaldo de semilla de 12 palabras, por lo que se niega a ejecutarse cuando stdin/stdout no son una TTY real, y ningún agente puede invocarlo:

npx -y @depixapp/mcp init            # create a new wallet
npx -y @depixapp/mcp init --restore  # import an existing 12-word mnemonic

Pide (o genera) una frase de contraseña — nunca se muestra — te guía a través del ritual de respaldo, y termina imprimiendo el bloque exacto mcpServers para pegar, con la frase de contraseña dejada como marcador de posición para que la completes:

{
  "mcpServers": {
    "depix": {
      "command": "npx",
      "args": ["-y", "@depixapp/mcp"],
      "env": {
        "DEPIX_API_KEY": "sk_test_YOUR_KEY",
        "DEPIX_WALLET_PASSPHRASE": "<the passphrase you typed>",
        "DEPIX_WALLET_DIR": "/Users/you/.depix-wallet"
      }
    }
  }
}

Limpia el historial de tu terminal después. Reinicia tu cliente MCP y pídele que ejecute wallet_status.

Ejecuta el servidor directamente para verificar:

DEPIX_API_KEY=sk_test_YOUR_KEY npx -y @depixapp/mcp

El autoalojamiento sobre HTTP NO es trivialmente seguro. Las herramientas de billetera no tienen autenticación propia y la semilla se carga en todo el proceso. Sobre stdio local eso está bien. Expuesto sobre HTTP, cualquiera que alcance el puerto puede vaciar la billetera — vincula a localhost y agrega tu propio bearer/mTLS + aislamiento de red, o no lo hagas.

Inicio rápido 3 — Pruebas en sandbox (el bucle completo)

Siempre prueba con una clave sk_test_ antes de sk_live_. Los QR de sandbox son marcadores de posición no pagables (SANDBOX-…-DO-NOT-PAY).

create_checkout — amount siempre es requerido; en la vía Pix predeterminada payer_tax_number también lo es (el CPF/CNPJ es requerido incluso en sandbox). Usa un CPF de prueba como 52998224725:
```
{ "amount": 1500, "payer_tax_number": "52998224725" }
```
Devuelve un id chk_…, un payment_url, un pix.qr_code de sandbox y is_live: false.
simulate_checkout_payment — { "checkout_id": "chk_…" } marca el checkout de sandbox como pagado (solo sandbox; los checkouts en vivo devuelven sandbox_only).
wait_for_checkout — { "checkout_id": "chk_…" }. El servidor sondea internamente y transmite el progreso; haces una llamada y devuelve { "status": "completed", "terminal": true } — sin bucle de sondeo en el cliente.

También puedes leer un depósito sintético: get_deposit_status con un id sandbox_… devuelve depix_sent.

Cobro en la vía DePix en lugar de Pix

create_checkout toma payment_method. El "pix" predeterminado es el flujo anterior. Con "depix" el pagador envía DePix de billetera a billetera en Liquid a la dirección dedicada del comerciante — no hay QR de Pix ni documento del pagador:

{ "amount": 9990, "payment_method": "depix", "expected_discount_pct": 10 }

La respuesta lleva depix en lugar de pix: address, el exacto amount_cents a enviar (monto nominal menos el descuento del comerciante, menos un ajuste de sub-centavo que hace que el valor sea único — esa unicidad es cómo se empareja el pago), el decimal amount que firma una billetera, asset_id y un uri listo para escanear. Envía cualquier otro monto o cualquier otro activo y el pago no puede acreditarse automáticamente, y un pago en cadena es irreversible.

La liquidación se observa en cadena: approved en la primera confirmación (~1 min), completed en la segunda. expires_in acepta 300–3600 s aquí (predeterminado 1800) en lugar de los 300–1200 de la vía Pix. La vía debe ser habilitada por el comerciante — de lo contrario, la API responde depix_not_enabled. Los checkouts DePix de sandbox son deliberadamente no pagables (dirección de marcador de posición, uri: null); manéjalos con simulate_checkout_payment.

Herramientas

22 herramientas de gateway — disponibles en ambos niveles. Los montos están en centavos de BRL.

Herramienta	API	Alcance
`create_checkout`	POST /api/checkouts	`merchant_write`
`get_checkout`	GET /api/checkouts/:id	`merchant_read`
`list_checkouts`	GET /api/checkouts	`merchant_read`
`simulate_checkout_payment`	POST /api/checkouts/:id/simulate-payment	`merchant_write` (solo sandbox)
`wait_for_checkout`	GET /api/checkouts/:id (bucle del servidor)	`merchant_read`
`create_product`	POST /api/products	`merchant_write`
`list_products`	GET /api/products	`merchant_read`
`get_product`	GET /api/products/:id	`merchant_read`
`update_product`	PATCH /api/products/:id	`merchant_write`
`activate_product`	POST /api/products/:id/activate	`merchant_write`
`deactivate_product`	POST /api/products/:id/deactivate	`merchant_write`
`set_featured_products`	POST /api/products/featured	`merchant_write`
`list_product_checkouts`	GET /api/products/:id/checkouts	`merchant_read`
`get_account`	GET /api/me	`merchant_read`
`get_deposit_status`	GET /api/deposits/:id	`wallet_read` (solo lectura)
`get_withdrawal_status`	GET /api/withdrawals/:id	`wallet_read` (solo lectura)
`open_support_ticket`	POST /api/tickets	cualquier clave (sin alcance)
`get_support_ticket`	GET /api/tickets/:id	cualquier clave (sin alcance)
`list_support_tickets`	GET /api/tickets	cualquier clave (sin alcance)
`reply_support_ticket`	POST /api/tickets/:id/messages	cualquier clave (sin alcance)
`attach_support_ticket_file`	POST /api/tickets/:id/attachments	cualquier clave (sin alcance)
`close_support_ticket`	POST /api/tickets/:id/close	cualquier clave (sin alcance)

Cobros (cobranças). create_product con kind: "charge" crea un enlace de pago con una fecha de vencimiento y multa/interés opcionales por retraso — alquiler, matrícula, una cuota. Se sirve en pay.depixapp.com/c/{id}, nunca aparece en la tienda pública del comerciante, y el monto se recalcula en cada visita (base + multa + interés prorrateado para el ciclo actual). Con recurrence el mismo enlace sigue funcionando mes tras mes, liquidando primero el ciclo impago más antiguo. list_products no devuelve cobros a menos que pases kind: "charge" (o "all"); las filas de cobro entonces llevan charge_state — ciclo actual, días de retraso, total de hoy.

No lo confundas con create_checkout, que acuña un pago único que se paga una vez y es de corta duración. Un cobro es el permanente.

Los últimos seis son el canal de soporte: abre un ticket, sondea la respuesta humana, responde, adjunta una captura de pantalla o archivo de diagnóstico/registro (base64, ~3 MB), o ciérralo (hasta 5 abiertos por cuenta). Las respuestas no se envían — sondea get_support_ticket. Los montos están en centavos de BRL. Una llamada a herramienta cuya clave carece del alcance requerido devuelve un error de herramienta insufficient_scope que nombra el alcance faltante — esa es la única forma de descubrir un alcance faltante (la API nunca lista los alcances de una clave).

27 herramientas wallet_* — solo el nivel local (npx). Firman en proceso con tu semilla; sin una devuelven wallet_not_configured.

Grupo	Herramientas
Estado y lecturas	`wallet_status`, `wallet_get_address`, `wallet_get_balances`, `wallet_list_transactions`, `wallet_get_guardrails`, `wallet_diagnostics`
Mover dinero	`wallet_send`, `wallet_create_deposit`, `wallet_wait_deposit`, `wallet_create_withdrawal`, `wallet_wait_withdrawal`
Convertir	`wallet_quote`, `wallet_convert`, `wallet_swap_quote`, `wallet_swap_execute`, `wallet_to_stablecoin`, `wallet_shift_usdt`
Lightning	`wallet_pay_lightning_invoice`, `wallet_receive_lightning`
Tarjetas de regalo	`wallet_list_giftcards`, `wallet_list_giftcard_products`, `wallet_giftcard_price`, `wallet_buy_giftcard`, `wallet_list_giftcard_orders`, `wallet_get_giftcard_order_status`
Recuperación	`wallet_recover`, `wallet_pending`

wallet_convert es la superficie de conversión principal (wallet_quote enumera las rutas); las herramientas a nivel de proveedor son la vía de escape. wallet_shift_usdt es la única ruta custodial (SideShift) y lo dice. Los montos llevan su unidad en el nombre del campo: amount_cents es centavos de BRL, amount_sats son las unidades base del activo.

Deliberadamente no hay herramienta para exportar la semilla, cambiar salvaguardas, editar las direcciones de pago, o pagar un QR de checkout de comerciante — ni siquiera desde un modelo completamente inyectado.

Configuración (pública, sin secretos)

Env	Significado	Predeterminado
`DEPIX_API_BASE`	URL base de la API (solo orígenes en lista de permitidos)	`https://api.depixapp.com`
`MCP_MAX_WAIT_SECONDS`	Presupuesto máximo de `wait_for_checkout`; producción establece ~780 (Vercel Pro)	`290` (seguro para Hobby)
`MCP_SERVER_VERSION`	Versión reportada en el handshake	versión del paquete
`MCP_ALLOWED_HOSTS`	Lista de permitidos de Host separada por comas (protección contra DNS-rebinding). Coincidencia exacta — sin comodines. Los despliegues de vista previa de Vercel añaden sus propios nombres de host automáticamente, por lo que normalmente no se establece	`mcp.depixapp.com`
`DEPIX_API_KEY`	solo modo stdio — tu clave de `sk_`	—

Solo nivel local (npx) — la mitad de la billetera:

Env	Significado	Predeterminado
`DEPIX_WALLET_PASSPHRASE`	Desbloquea la billetera local cifrada. *Requerida para las 27 herramientas de `wallet_`**; sin ella devuelven `wallet_not_configured`	—
`DEPIX_WALLET_DIR`	Dónde reside la billetera cifrada	`~/.depix-wallet`
`DEPIX_GUARDRAIL_*`	Límites BRL por transacción / ventana móvil de 24 h y lista de permitidos. Inmutable en tiempo de ejecución: configúralo aquí + reinicia	R$100/tx, R$500/día
`DEPIX_MCP_MAX_WAIT_SECONDS`	Tope para las herramientas de espera de la billetera	`900`

Deliberadamente no existe env para clave de API, token Eulen, HMAC o credencial de base de datos en el servidor remoto. En modo HTTP la clave llega por solicitud en el encabezado Authorization. La frase de contraseña y la semilla de la billetera existen solo en la máquina del operador — el despliegue alojado no lee ninguna y no tiene código que pudiera.

Endpoints

POST /mcp — el endpoint MCP Streamable HTTP (DELETE finaliza una sesión; GET devuelve 405 — este servidor sin estado no ofrece flujo SSE independiente).
GET /.well-known/mcp.json — documento de descubrimiento mínimo.
GET /api/health (también /) — estado del servicio.

Desarrollo

npm install
npm test           # vitest
npm run typecheck  # tsc --noEmit
npm run lint       # eslint
npm run build      # compile src (incl. the vendored engine) → dist
npm run guard:hosted   # the hosted deployment has no path to the wallet engine
npm run licenses:check # THIRD_PARTY_LICENSES matches the prod dep tree
npm run vendor:check   # src/vendor matches the pinned engine commit

Establece DEPIX_TEST_KEY=sk_test_… para ejecutar la prueba e2e de sandbox real (test/e2e/sandbox.test.ts), de lo contrario se omite.

El motor incluido (`src/vendor/`)

Las 27 herramientas de billetera provienen del motor de billetera DePix App, cuya fuente está incluida aquí desde un commit fijado en lugar de tomarse como dependencia npm.

vendor/engine.pin.json es la única fuente de verdad (repositorio + SHA completo de 40 caracteres).
npm run vendor:engine regenera src/vendor/** desde ese commit, estampando cada archivo con el encabezado Apache-2.0 y su procedencia. Nunca edites a mano nada bajo src/vendor/ — cámbialo upstream y actualiza la fijación.
El árbol está commiteado porque npm ci ejecuta prepare → build: las fuentes deben existir antes de que cualquier paso de instalación pudiera obtenerlas. La reproducibilidad proviene de npm run vendor:check, que CI ejecuta contra un checkout limpio del commit fijado y falla ante un solo byte de desviación.

Por qué el despliegue alojado no puede firmar

api/mcp.ts → src/http.ts → src/server.ts tiene cero ruta de importación a src/vendor/**. Ningún repositorio ejecuta un bundler de tree-shaking, por lo que ese grafo de importación es toda la garantía. scripts/check-hosted-isolation.mjs lo aplica dos veces — un recorrido estático de las fuentes TypeScript y un rastreo @vercel/nft de las entradas compiladas — y su --self-test demuestra que ambas verificaciones rechazan una entrada envenenada. Solo src/stdio.ts → src/unified.ts puede alcanzar el motor.

CI (.github/workflows/ci.yml) ejecuta typecheck + lint + test + build + las tres salvaguardas en cada push a main y cada PR, en Node 22 y 24 — esa es la puerta de corrección.

Publicación

La publicación está automatizada mediante GitHub Actions usando npm Trusted Publishing (OIDC) — sin token npm, sin solicitud de 2FA, y cada versión lleva procedencia de compilación. .github/workflows/publish-mcp.yml (en una etiqueta v*) publica el paquete npm y luego la entrada del MCP Registry (registry/server.json).

Para hacer una versión:

Actualiza la versión en package.json, registry/server.json (tanto el version de nivel superior como packages[].version) y el respaldo resolveServerVersion en src/config.ts — deben coincidir, y CI falla la versión si la etiqueta, package.json y la entrada npm del registro no coinciden (una prueba unitaria fija el respaldo de configuración). El MCP Registry es inmutable por versión, por lo que cualquier cosa que publique desde el árbol etiquetado debe estar correcta antes de la etiqueta.
Haz commit a main.

Etiqueta y empuja:

git tag v2.0.0 && git push origin v2.0.0

El flujo de trabajo verifica las versiones, re-verifica el motor incluido contra su commit fijado, publica en npm con procedencia, luego publica la entrada del registro (idempotente — re-ejecutar una etiqueta es un no-op seguro). Re-etiquetar una versión ya publicada omite ambas publicaciones.

Configuración única (ya hecha): el paquete está registrado como Trusted Publisher de npm para este repositorio con nombre de archivo de flujo de trabajo publish-mcp.yml (npmjs.com → paquete → Configuración → Trusted Publisher). No se almacenan secretos en el repositorio.

Prueba de humo de la versión

Después de un despliegue de vista previa/producción:

claude mcp add --transport http depix <url>/mcp --header "Authorization: Bearer sk_test_…"
Pide a Claude que ejecute get_account → devuelve el comerciante, is_live: false.
create_checkout (sandbox) → simulate_checkout_payment → wait_for_checkout → completed.

Empujar a main despliega a producción (mcp.depixapp.com). Valida en un despliegue de vista previa de Vercel antes de fusionar. Las vistas previas son accesibles de inmediato: un despliegue no productivo añade su propio VERCEL_URL y VERCEL_BRANCH_URL a la lista de permitidos de DNS-rebinding (resolveAllowedHosts), y producción no amplía nada. Si alguna vez necesitas permitir otro host, establece MCP_ALLOWED_HOSTS al nombre de host exacto — la lista de permitidos es una coincidencia exacta, por lo que *.vercel.app coincide con nada y dejaría la vista previa inaccesible.