Servidor MCP

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

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.

¿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 (endpoint /mcp/admin, claves de administrador ak_).

Requisitos

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

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)

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.

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.

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

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

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

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

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

Verificación

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.
En su cliente pida "list my VMs": el asistente llama a vm_list y muestra el resultado.
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

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

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

Servidor MCP ​

Qué hace ​

Requisitos ​

Preparar la infraestructura ​

Conexión (lado del cliente) ​

Cómo funciona ​

Reglas de seguridad ​

Límites ​

Verificación ​

Límites y notas ​

Resolución de problemas ​