Ir al contenido
Integraciones
Abrir .md
En esta página

Servidor MCP

Conecta Claude Code, Cursor o cualquier cliente MCP a un servidor local de Paymos: el agente monta la integración y verifica webhooks en sandbox.

@paymos/mcp es un servidor MCP local (Model Context Protocol). Tu agente de programación recibe seis herramientas de Paymos y la documentación para desarrolladores como recursos, y luego construye la integración por ti: crea facturas de sandbox, abre la página de pago, simula un pago, espera el estado paid, verifica la firma de un webhook y escribe el código de producción sobre un SDK de servidor.

El servidor se comunica por stdio y no abre puertos: llama a la Merchant API a través del SDK oficial con tu par de claves de prueba. Setup no muestra los valores secretos en su salida. Los registros del cliente y del modelo dependen de sus propios ajustes.

Requisitos

Conecta el cliente

npx -y @paymos/mcp setup

Elige tu cliente e introduce el par de claves de prueba. El secreto queda oculto mientras lo escribes. Puedes añadir el secreto de webhooks si vas a verificar firmas. Al terminar, reinicia el cliente o vuelve a conectar el servidor MCP para cargar las herramientas de Paymos.

Si ya sabes qué cliente vas a usar, indícalo en el comando:

npx -y @paymos/mcp setup --client codex
Cliente Valor de --client Archivo predeterminado
Codex codex $CODEX_HOME/config.toml o ~/.codex/config.toml
Claude Code claude-code ~/.claude.json
Claude Desktop claude-desktop claude_desktop_config.json en la carpeta de usuario de Claude de Windows/macOS
Kimi CLI kimi $KIMI_CODE_HOME/mcp.json o ~/.kimi-code/mcp.json
Cursor cursor ~/.cursor/mcp.json
Windsurf windsurf ~/.codeium/windsurf/mcp_config.json
OpenCode opencode OPENCODE_CONFIG o $XDG_CONFIG_HOME/opencode/ (si no, ~/.config/opencode/)
VS Code vscode .vscode/mcp.json en el directorio actual
Otros clientes generic Ruta indicada con --config

OpenCode usa opencode.jsonc si existe; en caso contrario, opencode.json. Para Cline, Roo Code o un cliente propio, elige generic y copia la ruta real desde los ajustes del cliente:

npx -y @paymos/mcp setup --client generic --config /ruta/al/archivo-mcp.json

También puedes cambiar la ruta de cualquier otro cliente con --config PATH. Claude Desktop necesita esa opción fuera de Windows y macOS. Usa --credentials-file PATH para elegir dónde guardar las claves, --dry-run para revisar los cambios sin escribir archivos ni mostrar secretos y --help para consultar las opciones.

Dónde quedan las claves

Las claves se guardan en $XDG_CONFIG_HOME/paymos/mcp/credentials.json; si no existe XDG_CONFIG_HOME, la ruta es ~/.config/paymos/mcp/credentials.json. El archivo del cliente solo contiene PAYMOS_CREDENTIALS_FILE con esa ruta. Mantén el archivo de claves fuera del proyecto.

Para configurar sin preguntas, define PAYMOS_API_KEY_ID y PAYMOS_API_SECRET en el entorno; PAYMOS_WEBHOOK_SECRET es opcional. Las variables anteriores y las opciones del servidor --api-key-id y --api-secret siguen funcionando. Al arrancar, cada campo toma primero el valor del entorno, después el de las opciones y por último el del archivo de claves.

Setup conserva los demás servidores, comentarios y ajustes del modelo. Repetirlo con los mismos datos deja una sola entrada. Si encuentra otra entrada de Paymos o claves distintas en el archivo de destino, se detiene sin sobrescribirlas. Revisa ese archivo y elige otra ruta si necesitas conservar ambas configuraciones.

Cliente y modelo

El cliente gestiona la conexión MCP. Puedes usar Codex, Kimi CLI, OpenCode, GLM en Claude Code o un modelo propio que admita llamadas a herramientas. Elige el modelo y su endpoint en los ajustes del cliente; setup añade el servidor de Paymos y conserva esos ajustes.

Configura el servidor a mano

Crea un archivo separado para las claves:

{"apiKeyId":"pk_test_…","apiSecret":"sk_test_…","webhookSecret":"whsec_…"}

En Unix, limita el acceso a tu usuario:

chmod 600 /ruta/absoluta/credentials.json

El servidor rechaza archivos que puedan leer otros usuarios o grupos. En Windows se usan los permisos existentes de la carpeta de tu cuenta. Omite webhookSecret si no vas a verificar firmas. Sustituye /ruta/absoluta/credentials.json por la ruta de ese archivo.

Clientes con mcpServers

Este ejemplo sirve para clientes con mcpServers, como Claude Code, Cursor y Kimi CLI:

{"mcpServers":{"paymos":{"command":"npx","args":["-y","@paymos/mcp"],"env":{"PAYMOS_CREDENTIALS_FILE":"/ruta/absoluta/credentials.json"}}}}

Codex

En Codex, añade el servidor al archivo TOML:

[mcp_servers.paymos]
command = "npx"
args = ["-y", "@paymos/mcp"]
[mcp_servers.paymos.env]
PAYMOS_CREDENTIALS_FILE = "/ruta/absoluta/credentials.json"

OpenCode

OpenCode usa mcp, con el comando completo en un array:

{"mcp":{"paymos":{"type":"local","command":["npx","-y","@paymos/mcp"],"environment":{"PAYMOS_CREDENTIALS_FILE":"/ruta/absoluta/credentials.json"},"enabled":true}}}

VS Code

Para VS Code, usa servers y el tipo stdio:

{"servers":{"paymos":{"type":"stdio","command":"npx","args":["-y","@paymos/mcp"],"env":{"PAYMOS_CREDENTIALS_FILE":"/ruta/absoluta/credentials.json"}}}}

Zed

Añade Zed a mano bajo context_servers. En Unix, el archivo global es ~/.config/zed/settings.json; .zed/settings.json pertenece al proyecto. En Windows, abre el archivo settings.json desde los ajustes de Zed. Setup no incluye un adaptador para Zed.

Comando de arranque en Windows

En Windows, usa cmd como comando y ["/d","/c","npx","-y","@paymos/mcp"] como argumentos. En OpenCode, ese mismo comando ocupa el array command, empezando por "cmd".

Qué puede hacer el agente

Herramienta Cometido
create_invoice Crea una factura de sandbox; idempotente por external_order_id; devuelve payment_url
get_invoice Lee el estado actual de una factura
list_invoices Lee una página de facturas con cursores y filtros
cancel_invoice Cancela una factura impagada guardando el motivo
simulate_invoice_payment Lleva una factura por los estados paid, paid_late, overpaid, underpay o cancel — solo sandbox
verify_webhook_signature Verifica una cabecera X-Webhook-Signature en local, sin llamar a la API

Cinco páginas de documentación viajan como recursos, de modo que el agente las lee dentro de la sesión en lugar de buscar en la red: paymos://docs/quick-start, paymos://docs/hosted-checkout, paymos://docs/webhooks, paymos://docs/testing-sandbox, paymos://docs/server-sdks.

Los nombres y esquemas de las herramientas existentes se conservan con este setup; paid_late amplía la simulación.

Solo sandbox

El servidor acepta únicamente pares de claves de prueba. Las claves de producción (pk_live_/sk_live_) y Payout (rk_…) se rechazan al arrancar y en cada llamada, con un error claro. Cuando el agente haya escrito y verificado tu integración, tu propio código pasa a producción con tus claves reales — el servidor MCP se queda fuera.

El servidor MCP alojado se ha aplazado a la fase 2. Aún no está disponible ni tiene fecha de publicación.

Siguientes pasos

Anterior SDK de servidor Siguiente Seguridad