---
title: Servidor MCP
description: Conecte asistentes de IA (Claude, Cursor, VS Code y otros) a la API mediante el endpoint MCP en /mcp: autenticación, clientes, herramientas y seguridad.
url: https://nexcmp.com/es/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Servidor MCP {#mcp-server}

> **Dónde encontrarlo en el portal:** API reference › Tools (`https://<your-domain>/apidoc`) muestra el endpoint y los fragmentos para clientes; las claves se crean en API keys (`/api-keys`). No hay ajustes en el panel de administración: el endpoint forma parte del panel.

## Qué hace {#what-it-does}

El **Model Context Protocol (MCP)** permite a un asistente de IA llamar herramientas. NexCMP ofrece un endpoint MCP en `https://<your-domain>/mcp`. Cada operación pública de la API se convierte en una **herramienta** (`vm_list`, `vm_start`, `billing_wallet`...), de modo que un cliente puede preguntar a su asistente «¿cuáles de mis VM están en ejecución?» o «detén la VM de staging». El asistente actúa únicamente con la clave de API y los permisos del cliente.

::: tip ¿Configurar el propio NexCMP con IA?
Esta página describe el endpoint MCP para **clientes** (`/mcp`). Para permitir que un asistente de IA configure su propio panel como administrador, consulte [Configurar con IA](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/) (endpoint `/mcp/admin`, claves de administrador `ak_`).
:::

## Requisitos {#requirements}

| Elemento | Requisito |
|---|---|
| Servidor | No requiere instalación: el endpoint es proporcionado por el panel y es accesible dondequiera que esté el panel. Su proxy inverso debe reenviar `/mcp` al panel. |
| Cliente | Una [clave de API](https://nexcmp.com/es/docs/developers/api-keys/) (`vk_...`) con los scopes que necesite el asistente. |
| Cliente | Un cliente MCP compatible con el transporte **Streamable HTTP** y una cabecera personalizada `Authorization`: Claude Code, Claude Desktop (mediante el puente `mcp-remote`), Cursor, VS Code con modo agente de Copilot y similares. |
| Versiones del protocolo | 2025-11-25, 2025-06-18 y 2025-03-26. |

## Preparar la infraestructura {#prepare-the-infrastructure}

Nada, más allá de asegurarse de que `https://<your-domain>/mcp` no esté bloqueado por un firewall o una regla de proxy. Los clientes MCP basados en navegador desde otro origen se rechazan a menos que ese origen esté permitido; los clientes de línea de comandos y de escritorio no envían cabecera `Origin` y funcionan tal cual.

## Conexión (lado del cliente) {#connect-customer-side}

1. Cree una clave de API en el portal (**API keys › Create key**) únicamente con los scopes que desee que use el asistente, una expiración corta y, si es posible, una restricción por IP.
2. Añada el servidor a su cliente. Reemplace `cloud.example.com` y la clave.

   **Claude Code**

   ```bash
   claude mcp add --transport http cloud https://cloud.example.com/mcp \
     --header "Authorization: Bearer vk_XXXX"
   ```

   **Cursor** (`~/.cursor/mcp.json` o `.cursor/mcp.json`; defina `CLOUD_API_KEY` en el entorno desde el que se inicia Cursor):

   ```json
   {
     "mcpServers": {
       "cloud": {
         "url": "https://cloud.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
       }
     }
   }
   ```

   **Claude Desktop** (requiere Node.js 18+; `claude_desktop_config.json`), mediante el puente `mcp-remote`:

   ```json
   {
     "mcpServers": {
       "cloud": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
         "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
       }
     }
   }
   ```

   Escriba la cabecera sin espacios después de los dos puntos e introduzca el valor completo en la variable de entorno, como se muestra arriba.

3. Reinicie el cliente y pídale que liste sus herramientas.


Compruebe la conexión sin un cliente:

```bash
curl -s https://cloud.example.com/mcp \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Cómo funciona {#how-it-works}

| Elemento | Detalle |
|---|---|
| Endpoint | `POST /mcp` con un mensaje JSON-RPC 2.0; la respuesta es `application/json`. `GET /mcp` responde 405 (sin flujo de servidor a cliente); `DELETE /mcp` finaliza la sesión. |
| Autenticación | Solo `Authorization: Bearer vk_...` (los tokens de sesión, cookies y claves de administrador se rechazan con 401 y una cabecera `WWW-Authenticate: Bearer`). |
| Sesión | `Mcp-Session-Id` es emitido por `initialize`, vinculado a esa clave, válido por 24 horas; máximo 16 sesiones por clave. |
| Herramientas | Una por cada operación pública de la API visible para la clave. El nombre de la herramienta es el comando de la CLI con `_` en lugar de espacios y guiones (`vm firewall add` se convierte en `vm_firewall_add`) y coincide con el `operationId` de OpenAPI. Una herramienta solo se muestra si la clave tiene su scope y el módulo está habilitado. |
| Capacidades | Solo herramientas (sin resources ni prompts). |
| Tamaño | Cuerpo de la solicitud de hasta 1 MB; texto de resultado de la herramienta de hasta aprox. 100 KB (el resto se trunca con una nota); una llamada tarda como máximo 55 segundos. |

### Reglas de seguridad {#safety-rules}

- **La misma puerta de enlace que REST.** Cada `tools/call` pasa por la propia canalización de solicitudes del panel: se aplican el alcance, el sitio, la restricción de IP, el límite de frecuencia, la idempotencia, las comprobaciones de propiedad (404 para recursos ajenos) y las cuotas. MCP no puede conceder nada que la clave no posea.
- **Confirmación.** Las herramientas con coste económico, de eliminación o que devuelven credenciales (tickets de consola, kubeconfig, secretos de S3 o SSH, restablecimientos de contraseña, nuevas claves) requieren el argumento `confirm: true`. La descripción de la herramienta indica al asistente que solo lo transmita una vez que el usuario lo haya aprobado, de modo que una instrucción oculta en una página web o registro no pueda activarla por sí sola.
- **Idempotencia.** Las herramientas de pago aceptan `idempotency_key`; si se omite, se deriva una clave estable a partir del nombre de la herramienta y sus argumentos, de modo que un reintento idéntico no pueda cobrar dos veces.
- **No expuestos como herramientas:** endpoints de streaming (el chat de AI Agent), tickets WebSocket de SSH o consola de un solo uso, descargas de binarios y los endpoints de la aplicación VPN (`/v1/ext/*`).
- **Nunca posible:** la API nunca permite recargas, cambios de contraseña, eliminar la cuenta o crear claves, por lo que ningún asistente puede realizarlos.

### Límites {#limits}

| Límite | Predeterminado |
|---|---|
| Llamadas a herramientas por clave | 60 por minuto |
| Solicitudes MCP por clave | 240 por minuto |
| Más los límites habituales de clave y cuenta | Consulte [REST API](https://nexcmp.com/es/docs/developers/api/#rate-limits) |

Si se supera el límite, el endpoint responde HTTP 429 con un error JSON-RPC y `Retry-After`.

## Verificación {#verify}

1. El comando `curl` anterior devuelve un resultado JSON-RPC con una lista `tools`. Solo aparecen las herramientas que coinciden con los alcances de la clave.
2. En su cliente pida "list my VMs": el asistente llama a `vm_list` y muestra el resultado.
3. En el portal, la hora de **Last used** de la clave se actualiza y las llamadas de escritura aparecen en **Key usage log**.

## Límites y notas {#limits-notes}

- **Inicio de sesión en el navegador (OAuth).** La página de referencia también describe el inicio de sesión a través del navegador para clientes compatibles con MCP OAuth. En una instalación de NexCMP, el método compatible y probado es la clave API (o `cmp login` para la CLI).
- **Los sitios de revendedores** no muestran la sección MCP; sus clientes utilizan el dominio del revendedor para la API.
- **Mínimo privilegio.** Cree una clave dedicada por asistente, primero con alcances de lectura; añada alcances de escritura solo cuando sea necesario.
- Revoque la clave en **API keys** para cortar el acceso del asistente de inmediato.

## Resolución de problemas {#troubleshooting}

| Síntoma | Causa | Solución |
|---|---|---|
| 401 con `WWW-Authenticate: Bearer` | Sin clave, clave incorrecta o un token de sesión | Envíe `Authorization: Bearer vk_...`. |
| 403 sobre `Origin` | Una página del navegador en otro origen | Utilice un cliente de escritorio o CLI, o solicite a su administrador que permita el origen (`mcp_allowed_origins`). |
| 404 en una solicitud con `Mcp-Session-Id` | La sesión pertenece a otra clave o ha caducado | Ejecute `initialize` de nuevo. |
| 405 en `GET /mcp` | Esperado: el servidor no tiene flujo de eventos | Utilice solo POST (los clientes lo hacen automáticamente). |
| La lista de herramientas es corta | Alcances de la clave o módulos | Añada alcances a la clave; habilite el módulo. |
| La herramienta responde que necesita `confirm: true` | Herramienta de pago, de eliminación o confidencial | El asistente debe definir `confirm` después de que usted lo apruebe. |
| 429 | Límite de frecuencia de MCP o de la clave | Espere a `Retry-After`. |
| El cliente no puede conectarse con un encabezado | Cliente sin compatibilidad con encabezados personalizados | Utilice el puente `mcp-remote`. |