Servidor MCP

OrcaRail publica un servidor oficial de Model Context Protocol (MCP) como @orcarail/mcp. Se ejecuta en local mediante stdio y envuelve el SDK @orcarail/node, para que agentes de programación con IA como Claude Code, Cursor y Codex puedan crear payment intents, gestionar suscripciones, mantener tu catálogo de productos y consultar tipos de cambio por ti; el mismo modelo de distribución que @stripe/mcp de Stripe.

Código fuente: github.com/OrcaRail/mcp

Qué puedes hacer con él

Una vez conectado, puedes pedirle a tu agente cosas como:

«Crea un payment intent de 25 $ en USDC en Polygon con la URL de retorno https://myapp.com/success y dame el enlace de pago.»
«Lista mis suscripciones activas y cancela la de [email protected] al final del periodo.»
«Crea un producto llamado Pro Plan con un precio recurrente de 29 $/mes.»
«¿Cuánto son ahora 500 EUR en USDC?»
«¿Cuál es el estado del payment intent 550e8400-…?»

El agente llama a las herramientas MCP correspondientes. Las herramientas públicas (rates.*, pay.*) no necesitan credenciales; las privadas se autentican con tu clave y tu secreto de API contra la API REST de OrcaRail.

Requisitos

Node.js 18 o posterior
Para las herramientas privadas: una clave y un secreto de API de OrcaRail (ak_… / sk_…) del panel
Las herramientas públicas de tipos de cambio y pago funcionan sin credenciales

Inicio rápido

Solo herramientas públicas (sin credenciales):

npx -y @orcarail/mcp --tools=all

Con credenciales para las herramientas privadas (mejor como variables de entorno):

export ORCARAIL_API_KEY=ak_live_xxx
export ORCARAIL_API_SECRET=sk_live_xxx
npx -y @orcarail/mcp --tools=all

O pasa parámetros:

npx -y @orcarail/mcp --tools=all --api-key=ak_live_xxx --api-secret=sk_live_xxx

El servidor habla MCP por stdin/stdout: está pensado para que lo lance un cliente MCP (consulta las secciones de clientes más abajo), no para usarlo de forma interactiva.

Configuración

Cada opción está disponible como parámetro de la CLI o como variable de entorno. Los parámetros tienen prioridad. Para los secretos, mejor variables de entorno.

Parámetro	Variable de entorno	Obligatorio	Descripción
`--api-key`	`ORCARAIL_API_KEY`	Para las herramientas privadas	Clave de API (`ak_…`)
`--api-secret`	`ORCARAIL_API_SECRET`	Para las herramientas privadas	Secreto de API (`sk_…`)
`--api-base`	`ORCARAIL_API_BASE`	No	URL base de la API. Por defecto `https://api.orcarail.com/api/v1`
`--organization-id`	`ORCARAIL_ORGANIZATION_ID`	No	Organización por defecto para las herramientas del catálogo (`products.`, `prices.`)
`--tools`	—	No	`all` (por defecto) o una lista de nombres de herramientas separados por comas

Restringir las herramientas

Por defecto se exponen todas las herramientas. Usa --tools para limitar lo que puede hacer el agente; por ejemplo, solo leer y crear, sin cancelaciones ni borrados:

npx -y @orcarail/mcp \
  --tools=payment_intents.create,payment_intents.retrieve,subscriptions.list,rates.get_fiat_quote \
  --api-key=ak_live_xxx --api-secret=sk_live_xxx

Los nombres desconocidos se ignoran sin avisar; el servidor solo registra las herramientas que coinciden.

API autoalojada o local

Apunta --api-base a tu propio despliegue:

npx -y @orcarail/mcp --tools=all \
  --api-base=http://127.0.0.1:3000/api/v1 \
  --api-key=ak_test_xxx --api-secret=sk_test_xxx

Configuración del cliente

Claude Code

claude mcp add orcarail -- npx -y @orcarail/mcp --tools=all --api-key=ak_live_xxx --api-secret=sk_live_xxx

O mantén los secretos fuera de la línea de comandos con variables de entorno:

claude mcp add orcarail \
  -e ORCARAIL_API_KEY=ak_live_xxx \
  -e ORCARAIL_API_SECRET=sk_live_xxx \
  -- npx -y @orcarail/mcp --tools=all

Compruébalo con claude mcp list y después pide a Claude Code, por ejemplo, «lista mis suscripciones de OrcaRail».

Cursor

Añade esto a .cursor/mcp.json en tu proyecto (o a ~/.cursor/mcp.json para todos los proyectos):

{
  "mcpServers": {
    "orcarail": {
      "command": "npx",
      "args": ["-y", "@orcarail/mcp", "--tools=all"],
      "env": {
        "ORCARAIL_API_KEY": "ak_live_xxx",
        "ORCARAIL_API_SECRET": "sk_live_xxx"
      }
    }
  }
}

Cursor detecta el servidor automáticamente; comprueba en Settings → MCP que está en marcha.

Codex

Añade esto a ~/.codex/config.toml:

[mcp_servers.orcarail]
command = "npx"
args = ["-y", "@orcarail/mcp", "--tools=all"]

[mcp_servers.orcarail.env]
ORCARAIL_API_KEY = "ak_live_xxx"
ORCARAIL_API_SECRET = "sk_live_xxx"

Otros clientes MCP

Cualquier cliente compatible con servidores MCP por stdio funciona con la misma forma: comando npx, argumentos ["-y", "@orcarail/mcp", "--tools=all"]. Las credenciales (ORCARAIL_API_KEY / ORCARAIL_API_SECRET) son opcionales para las herramientas públicas y obligatorias para las privadas. En Claude Desktop, añade el mismo bloque JSON que en Cursor a claude_desktop_config.json.

Live frente a sandbox

El servidor detecta su modo a partir de la clave de API y se lo indica a tu agente mediante sus instrucciones MCP y la herramienta account.get_mode:

ak_test_… (organización sandbox): solo testnets, sin fondos reales. Está disponible payment_intents.simulate.
ak_live_…: fondos reales. Se pide al agente que te confirme antes de cualquier escritura.
Sin clave: solo herramientas públicas.

Usa una clave sandbox mientras construyes con un agente.

Referencia de herramientas

Los nombres de las herramientas siguen el formato resource.action. Todas las respuestas son los objetos de la API de OrcaRail tal cual, serializados como JSON.

Payment intents

Herramienta	Argumentos	Descripción
`payment_intents.create`	`return_url` (obligatorio); `price_id` o `amount` + `currency` + `tokenId` + `networkId`; opcionales `cancel_url`, `description`, `metadata`, `expires_at`, `payment_method_types`, `withdrawal_addresses`	Crea un payment intent. Devuelve el intent con `client_secret` y el enlace de pago
`payment_intents.retrieve`	`id`	Obtiene el estado actual
`payment_intents.update`	`id` + cualquier campo actualizable	Actualiza antes de la confirmación
`payment_intents.confirm`	`id`, `client_secret`, `return_url`	Confirma y obtiene la URL de redirección a la página de pago alojada
`payment_intents.complete`	`id`	Marca como en procesamiento cuando el cliente vuelve a tu URL de éxito
`payment_intents.cancel`	`id`	Cancela el intent

tokenId y networkId son UUID; consulta Redes y tokens para los valores actuales.

Suscripciones

Herramienta	Argumentos	Descripción
`subscriptions.create`	`description` (obligatorio); `price_id` o `interval` + `amount` + `currency` + `token_id` + `network_id`; opcionales `collection_method`, `total_cycles`, `trial_period_days`, `trial_end`, `payer_email`, `payer_user_id`, `billing_cycle_anchor`, `cancel_at`, `cancel_at_period_end`, `days_until_due`, `interval_count`, `metadata`, `withdrawal_addresses`, `return_url`, `cancel_url`	Crea una suscripción recurrente
`subscriptions.retrieve`	`id`	Obtiene una suscripción
`subscriptions.update`	`id` + cualquier campo actualizable, incluido `pause_collection`	Actualiza una suscripción
`subscriptions.cancel`	`id`, `cancellation_details` opcional (`comment`, `feedback`)	Cancela
`subscriptions.resume`	`id`	Reanuda una suscripción en pausa
`subscriptions.list`	Opcionales `status`, `collection_method`, filtros de rango `created`/`current_period_start`/`current_period_end`, `limit`, `starting_after`, `ending_before`	Lista con paginación por cursor
`subscriptions.list_payment_links`	`id`, opcionales `limit`, `starting_after`, `ending_before`	Facturas por ciclo (enlaces de pago) de una suscripción

Catálogo: productos

Las herramientas del catálogo trabajan sobre una organización. Pasa organization_id en cada llamada o define uno por defecto con --organization-id / ORCARAIL_ORGANIZATION_ID.

Herramienta	Argumentos	Descripción
`products.list`	`organization_id` opcional	Lista los productos
`products.create`	`name` (obligatorio); opcionales `description`, `active`, `metadata`, `default_price`, `marketing_features` y más	Crea un producto
`products.update`	`product_id` + cualquier campo actualizable	Actualiza un producto
`products.delete`	`product_id`	Elimina un producto

Catálogo: precios

Herramienta	Argumentos	Descripción
`prices.list`	opcionales `organization_id`, `active`, `recurring`, `limit`	Lista los precios
`prices.create`	`unit_amount_decimal`, `currency`, `token_id`, `network_id` (obligatorios); `product` o `product_data` en línea; opcionales `recurring` (`interval`, `interval_count`, `trial_period_days`), `nickname`, `lookup_key`, `active`, `metadata`	Crea un precio de pago único o recurrente
`prices.update`	`price_id` + cualquier campo actualizable	Actualiza un precio
`prices.deactivate`	`price_id`	Desactiva un precio

Tipos de cambio (públicas, sin credenciales)

Herramienta	Argumentos	Descripción
`rates.get_fiat_quote`	`amount`, `currency`	Convierte un importe fiat a USD/USDC
`rates.list_currencies`	`active` opcional	Lista las monedas fiat compatibles

Pago (páginas de pago alojadas, públicas, sin credenciales)

Herramienta	Argumentos	Descripción
`pay.get_by_slug`	`slug`	Obtiene los datos del pago por el slug de la página de pago alojada
`pay.cancel_by_slug`	`slug`	Cancela un payment intent por su slug de pago

Flujos de trabajo de ejemplo

Crear un pago y obtener el enlace de pago

Pide a tu agente:

Crea en OrcaRail un payment intent de 50 USD con USDC en Polygon, con la URL de retorno https://myshop.com/thanks; después confírmalo y dame la URL de pago para el cliente.

El agente llamará a payment_intents.create, después a payment_intents.confirm con el client_secret devuelto, y te dará la URL de pago alojada.

Configurar un producto de suscripción

Crea en OrcaRail un producto «Pro Plan» con un precio recurrente de 29 $/mes en USDC y después crea una suscripción para [email protected] con ese precio.

El agente encadena products.create → prices.create (con recurring.interval: "month") → subscriptions.create (con el nuevo price_id y payer_email).

Investigar un pago

Busca el payment intent 550e8400-e29b-41d4-a716-446655440000 y dime su estado, su importe y la última transacción.

Gestión de errores

Los fallos de la API se devuelven al agente como errores de herramienta con el estado HTTP, el tipo de error y el mensaje de la API intactos (por ejemplo, API error (401): [authentication_error]: …). Normalmente los agentes los leen y corrigen la siguiente llamada; no se reintenta nada automáticamente.

Llamar a una herramienta privada sin credenciales devuelve un error claro: define ORCARAIL_API_KEY y ORCARAIL_API_SECRET (o los parámetros de la CLI equivalentes).

Seguridad

Las claves dan acceso total a la organización vinculada a la clave de API. Trata los archivos de configuración de MCP con el mismo cuidado que los archivos .env.
Usa variables de entorno en lugar de argumentos --api-key=… en línea, para que los secretos no acaben en el historial del shell ni en configuración versionada.
Nunca subas claves live. Si usas un .cursor/mcp.json a nivel de proyecto, mantén la clave fuera de git (usa referencias a variables de entorno o un archivo solo local).
Limita con --tools. Expón solo las operaciones que necesita tu agente; por ejemplo, excluye products.delete y subscriptions.cancel en flujos principalmente de lectura.
Usa claves de prueba durante el desarrollo y rota en el panel cualquier clave que pueda haberse filtrado.

Solución de problemas

Síntoma	Solución
`Missing credentials for this tool`	Define `ORCARAIL_API_KEY`/`ORCARAIL_API_SECRET` (o `--api-key`/`--api-secret`) para las herramientas privadas
`Authentication error` en todas las llamadas	Comprueba el par clave/secreto en el panel; asegúrate de no mezclar credenciales de prueba y live
`organization_id is required`	Pasa `organization_id` en la llamada a la herramienta o arranca con `--organization-id`
Falta una herramienta en el cliente	Revisa tu filtro `--tools`: los nombres deben coincidir exactamente (por ejemplo `payment_intents.create`)
El cliente no puede arrancar el servidor	Asegúrate de que Node.js 18+ está en el PATH que usa el cliente; prueba `npx -y @orcarail/mcp --help` en una terminal

Qué puedes hacer con él​

Requisitos​

Inicio rápido​

Configuración​

Restringir las herramientas​

API autoalojada o local​

Configuración del cliente​

Claude Code​

Cursor​

Codex​

Otros clientes MCP​

Live frente a sandbox​

Referencia de herramientas​

Payment intents​

Suscripciones​

Catálogo: productos​

Catálogo: precios​

Tipos de cambio (públicas, sin credenciales)​

Pago (páginas de pago alojadas, públicas, sin credenciales)​

Flujos de trabajo de ejemplo​

Crear un pago y obtener el enlace de pago​

Configurar un producto de suscripción​

Investigar un pago​

Gestión de errores​

Seguridad​

Solución de problemas​

Relacionado​