# 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](https://modelcontextprotocol.io)). 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](/es/docs/server-sdks.md).

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

- Node.js 20 o superior
- Un par de claves de prueba desde [**Panel → Desarrollador → Claves de API**](/es/docs/api-keys.md):
  un identificador `pk_test_` y un secreto `sk_test_`

## Conecta el cliente

```sh
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:

```sh
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:

```sh
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:

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

En Unix, limita el acceso a tu usuario:

```sh
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:

```json
{"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:

```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:

```json
{"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`:

```json
{"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](/es/docs/testing.md) |
| `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

- [Inicio rápido](/es/docs/quick-start.md) — el flujo que el agente automatiza, hecho a mano una vez
- [Pruebas en el sandbox](/es/docs/testing.md) — qué cubre la simulación
- [SDK de servidor](/es/docs/server-sdks.md) — lo que llamará el código generado
- [Webhooks](/es/docs/webhooks.md) — eventos, reintentos y verificación de firmas