---
title: Conectar un cliente de IA (MCP)
description: Conecte Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai, ChatGPT o SDKs de OpenAI al endpoint admin MCP con todas las herramientas.
url: https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Conectar un cliente de IA (MCP) {#connect-an-ai-client-mcp}

> **En el panel de administración:** System › Settings › API & AI agents (`/agent/keys`), la pestaña **Connect an AI** muestra la URL del endpoint y un fragmento listo para copiar para cada cliente, con la clave que acaba de crear.

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

El **Model Context Protocol (MCP)** permite que un cliente de IA invoque herramientas. Su panel ofrece un servidor MCP de administración en `https://cloud.example.com/mcp/admin`. Conecte su propia herramienta de IA a él y pregunte en lenguaje natural: "¿qué falta por configurar?", "añadir mi clúster de Proxmox", "crear planes con un 40% de margen". El cliente invoca las herramientas de administración indicadas a continuación; el panel comprueba los scopes, le solicita confirmación antes de cualquier acción de riesgo y registra cada llamada.

::: info Dos endpoints MCP
`/mcp` es el endpoint de **clientes** (claves API de clientes, `vk_`; consulte [MCP server](https://nexcmp.com/es/docs/developers/mcp/)). `/mcp/admin` es el endpoint de **administración** descrito aquí (claves de administración `ak_` u OAuth). Ambos nunca se mezclan: las herramientas de administración no son visibles en `/mcp` y `/mcp/admin` solo acepta claves de administración.
:::

## Requisitos {#requirements}

| Elemento | Requisito |
|---|---|
| Endpoint | `https://cloud.example.com/mcp/admin` en el propio dominio de su panel. Copie la URL exacta desde la pestaña **Connect an AI**. La misma página indica una URL local (`http://127.0.0.1:<port>/mcp/admin`) para las herramientas que se ejecutan en el propio servidor. |
| Credenciales | Una [clave API de administración](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/) (`ak_...`) con los scopes deseados, **o** inicio de sesión mediante OAuth para conectores web ([OAuth connectors](https://nexcmp.com/es/docs/configure-with-ai/oauth-connectors/)). |
| Cliente | Cualquier cliente MCP compatible con el transporte **Streamable HTTP** y un encabezado `Authorization` personalizado. Versiones de protocolo 2025-11-25, 2025-06-18 y 2025-03-26. |
| Red | Si coloca su propio proxy inverso delante del panel, este debe reenviar `/mcp/admin`. Los conectores web (claude.ai, ChatGPT) se conectan desde los servidores del proveedor, por lo que la URL debe ser accesible desde internet. |

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

No hay nada que instalar en el servidor. Si restringe la clave por IP, asegúrese de que la dirección desde la que se conecta su cliente esté dentro del rango. Pruebe primero la conectividad:

```bash
curl -i -X POST https://cloud.example.com/mcp/admin
```

Una respuesta de `401` con un encabezado `WWW-Authenticate: Bearer ... resource_metadata=...` indica que el endpoint está activo y solicita credenciales.

## Conectar en NexCMP {#connect-in-nexcmp}

1. Cree una clave: **System › Settings › API & AI agents › API keys › New key**. Para una primera prueba, use solo `admin:read`; agregue scopes de escritura cuando los necesite. Consulte [Admin API keys](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/).
2. Abra la pestaña **Connect an AI**. Mientras el cuadro de diálogo de «clave creada» siga visible, cada fragmento a continuación ya contendrá su clave real. De lo contrario, mostrará el marcador de posición `ak_YOUR_KEY`.
3. Copie el fragmento correspondiente a su cliente y ejecútelo o péguelo como se describe a continuación.

![Pestaña Connect an AI con la URL de MCP y una tarjeta con botón de copia para cada cliente](https://nexcmp.com/es/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

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

Luego inicie `claude` y pregunte "listar las herramientas de nexcmp" o "¿qué falta por configurar?".

Verificado el 30/10/2026 con Claude Code 2.1: `claude mcp add --transport http …` registra el servidor (añada `-s project` para mantenerlo en el `.mcp.json` del proyecto; Claude Code le solicitará aprobar los servidores del proyecto la primera vez). Para scripts, `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` se ejecuta sin la solicitud de aprobación y permite que Claude use únicamente las herramientas del panel.

### Claude Desktop {#claude-desktop}

Requiere Node.js 18 o posterior. Añada esto a `claude_desktop_config.json` (utiliza el puente `mcp-remote`) y reinicie Claude Desktop:

```json
{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}
```

Si su sistema altera el espacio en el argumento del encabezado, coloque el valor completo en una variable de entorno, exactamente igual que para el endpoint de clientes: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` con `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`.

### claude.ai (conector personalizado) {#claude-ai-custom-connector}

No se necesita ninguna clave: inicia sesión con OAuth. En claude.ai abra la configuración de conectores, agregue un conector personalizado, pegue `https://cloud.example.com/mcp/admin`, luego inicie sesión con su cuenta de administrador de NexCMP y elija los permisos en la pantalla de consentimiento. Detalles: [OAuth connectors](https://nexcmp.com/es/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (modo desarrollador) {#chatgpt-developer-mode}

No se necesita clave. En ChatGPT active el modo desarrollador, agregue un conector MCP con la URL `https://cloud.example.com/mcp/admin`, elija OAuth e inicie sesión con su cuenta de administrador de NexCMP. Detalles: [OAuth connectors](https://nexcmp.com/es/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

Añada a `~/.codex/config.toml`:

```toml
[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"
```

Luego exporte la clave en el shell que inicia Codex:

```bash
export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth
```

::: tip `codex exec` no interactivo
En `codex exec` (scripts, CI) Codex no pregunta antes de llamar a las herramientas y omite aquellas que modifican datos. Añada `default_tools_approval_mode = "approve"` bajo `[mcp_servers.nexcmp]` para permitirle ejecutarlas; el panel seguirá devolviendo una vista previa y solicitando confirmación para acciones relacionadas con dinero, seguridad y eliminación. Comprobado con Codex CLI 0.166 el 30/10/2026.
:::

### Gemini CLI {#gemini-cli}

Añada a `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

Gemini CLI desactiva los servidores MCP en carpetas en las que no confía. Inícielo en una carpeta de confianza (o confíe en ella cuando lo solicite) y luego compruébelo con `gemini mcp list` — muestra `nexcmp … Connected`. Puede mantener la clave fuera del archivo con `"Authorization": "Bearer $NEXCMP_KEY"`. Comprobado con Gemini CLI 0.66 el 30/10/2026.

### Cursor {#cursor}

Añada a `~/.cursor/mcp.json` (o `.cursor/mcp.json` en un proyecto):

```json
{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

::: tip Mantenga la clave fuera de los archivos de configuración
Cuando el cliente lo admita, lea la clave desde una variable de entorno en lugar de escribirla en el archivo: Codex lo hace de forma predeterminada (`bearer_token_env_var`) y Cursor admite `"Bearer ${env:NEXCMP_KEY}"`. Nunca haga commit de un archivo que contenga una clave.
:::

### OpenAI Agents SDK (Python) {#openai-agents-sdk-python}

```python
from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)
```

Una ejecución completa (comprobada con `openai-agents` 0.24 el 30/10/2026 — una herramienta de lectura, seguida de un cambio de saldo que devolvió la vista previa de confirmación y se aplicó en la segunda llamada con `confirm_token`):

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())
```

### OpenAI Responses API {#openai-responses-api}

Pase el servidor como una herramienta de tipo `mcp`. Mantenga `require_approval` en `always` para que su programa le solicite confirmación antes de cada llamada:

```json
{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}
```

### Cualquier otra opción (HTTP estándar) {#anything-else-plain-http}

Un cliente sin MCP puede llamar a las mismas herramientas a través de HTTP. `GET /v1/admin/agent/tools` las lista, `POST /v1/admin/agent/tools/<name>` ejecuta una con un cuerpo JSON de argumentos y `GET /v1/admin/openapi.json` devuelve una descripción de OpenAPI 3.1 (cada herramienta es una operación). Todas requieren `Authorization: Bearer ak_...`.

## Verificación {#verify}

1. Sin un cliente, liste las herramientas:

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

   La respuesta es un resultado JSON-RPC con las herramientas que permiten sus ámbitos.
2. En su cliente, solicite "run system_health". Devuelve alertas, el estado de la infraestructura conectada, pagos, correo electrónico, AI y el estado de la licencia.
3. Abra **API & AI agents › Activity**: las llamadas se listan con el nombre del cliente y `mcp`.
4. En el servidor, `sudo nexcmp status` muestra una línea "MCP admin" que indica `ready` cuando el endpoint responde (HTTP 401 sin clave es el estado correcto).

## Herramientas {#tools}

El servidor ofrece 58 herramientas. Un cliente solo ve las herramientas que permiten los ámbitos de su clave: las herramientas de lectura requieren `admin:read`, las de escritura requieren su propio ámbito. Las herramientas de escritura también reciben un argumento opcional `confirm_token` (consulte [Confirmación](#confirmation-confirm-token)). Los argumentos se validan con el esquema de cada herramienta: los argumentos desconocidos o mal escritos se rechazan con un mensaje que los especifica.

Los precios están en USD: los precios de los planes en dólares por hora (`hourly_usd`) y los saldos en centavos. Los secretos se pueden configurar, pero nunca se devuelven.

### Resumen y registros {#overview-and-logs}

| Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación |
|---|---|---|---|---|
| `system_health` | Alertas que requieren atención, estado de la infraestructura, pagos, correo electrónico, AI, estado de la licencia y de las actualizaciones. | `admin:read` | No | No |
| `setup_checklist` | Qué está configurado y qué queda pendiente: licencia, infraestructura, zona, plantillas de SO, planes, pagos, correo electrónico, personalización de marca, avisos legales y pedido de prueba. | `admin:read` | No | No |
| `license_status` | Estado de la licencia y comprobación de si existe una versión más reciente de NexCMP. | `admin:read` | No | No |
| `audit_search` | Busca en el registro de auditoría de administración y en el registro de claves de API. | `admin:read` | No | No |

### Configuración, marca, legal, módulos {#settings-branding-legal-modules}

| Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación |
|---|---|---|---|---|
| `settings_get` | Lee la configuración general (`keys` filtra; un `*` final coincide con un prefijo). | `admin:read` | No | No |
| `settings_update` | Modifica la configuración general desde un objeto plano `values`. Solo se aceptan las claves listadas por `settings_get`. | `settings:write` | Sí | Cuando una clave afecta a pagos, seguridad de inicio de sesión, ajustes globales del sitio o precios |
| `branding_get` | Nombre de marca, color, moneda de visualización, nombre del vendedor y URL del logotipo y favicon. | `admin:read` | No | No |
| `branding_update` | Establece el nombre de marca (hasta 60 caracteres), el color (`#rrggbb`), la moneda de visualización (`usd` o `vnd`) y el nombre del vendedor. | `settings:write` | Sí | No |
| `branding_logo_set` | Subir un logotipo claro u oscuro, o un favicon, desde una URL https o base64 (PNG, JPEG, WEBP, ICO o SVG, hasta 512 KB). | `settings:write` | Sí | No |
| `legal_get` | Términos de servicio y política de privacidad (inglés y vietnamita) y los valores neutrales predeterminados. | `admin:read` | No | No |
| `legal_update` | Definir el texto de términos y privacidad (markdown simple, sin HTML, hasta 50 KB cada uno). Una cadena vacía restaura el valor predeterminado. | `settings:write` | Sí | No |
| `modules_get` | Qué módulos opcionales están activados y cuáles se pueden alternar. | `admin:read` | No | No |
| `module_set` | Activar o desactivar un módulo opcional (`key` debe ser uno de `settable`). | `settings:write` | Sí | No |

### Correo electrónico y alertas {#email-and-alerts}

| Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación |
|---|---|---|---|---|
| `smtp_get` | Configuración del correo saliente (contraseña oculta) y estado de la cola. | `admin:read` | No | No |
| `smtp_configure` | Definir el servidor SMTP. Cambiar el host, el puerto o la seguridad requiere ingresar la contraseña de nuevo. | `settings:write` (+ `secrets:write` para la contraseña) | Sí | No |
| `smtp_test` | Enviar un correo de prueba real con la configuración guardada. | `settings:write` | Envía un correo | No |
| `telegram_get` | Canales de notificación de administración (chat IDs; los tokens del bot nunca se devuelven). | `admin:read` | No | No |
| `telegram_configure` | Agregar o actualizar el canal de alertas de Telegram (bot token y chat ID) y activar o desactivar las alertas de administración. | `settings:write` (+ `secrets:write` para el token) | Sí | No |
| `telegram_test` | Enviar un mensaje de prueba al canal de Telegram. | `settings:write` | Envía un mensaje | No |

### Pagos y monedas {#payments-and-currency}

| Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación |
|---|---|---|---|---|
| `payments_get` | Estado de Stripe, PayPal, cripto (USDT) y transferencia bancaria, además de canales habilitados y comisiones. | `admin:read` | No | No |
| `payment_configure` | Configurar las credenciales de una pasarela (`stripe`, `paypal`, `crypto` o `bank`). | `billing:write` (+ `secrets:write`) | Sí | Siempre |
| `payment_test` | Verificar con el proveedor las credenciales guardadas de una pasarela. | `billing:write` | No | No |
| `currency_get` | Moneda de visualización y tasa de cambio de USD a VND (automática o manual). | `admin:read` | No | No |
| `currency_set` | Definir la moneda de visualización o una tasa manual (0 significa automática; de lo contrario, entre 15000 y 50000). | `billing:write` | Sí | Al cambiar la tasa manual |

### Infraestructura y zonas {#infrastructure-and-zones}

| Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación |
|---|---|---|---|---|
| `cloudstack_get` | Endpoint de CloudStack guardado, IDs de zona y red (claves ocultas). | `admin:read` | No | No |
| `cloudstack_test` | Probar un endpoint con un API key y secret sin guardar; enumera las zonas. | `infra:write` (+ `secrets:write`, ya que transmite las claves) | No | No |
| `cloudstack_connect` | Guardar la conexión con CloudStack. | `infra:write` (+ `secrets:write`) | Sí | Siempre |
| `proxmox_list` | Clústeres de Proxmox VE agregados como fuentes, junto con su estado de salud. | `admin:read` | No | No |
| `proxmox_add` | Agregar un clúster de Proxmox VE con un API token (`user@realm!tokenid`) y su secret. | `infra:write` (+ `secrets:write`) | Sí | No |
| `proxmox_test` | Conectar a un clúster por ID; la primera conexión correcta fija su certificado TLS. | `infra:write` | Sí | No |
| `proxmox_attach_zone` | Comercializar un clúster de Proxmox en una zona existente, opcionalmente con un nodo como región. | `infra:write` | Sí | No |
| `zones_list` | Zonas (ubicaciones) que los clientes pueden elegir. | `admin:read` | No | No |
| `zone_create` | Crear una zona. | `infra:write` | Sí | No |

### Catálogo y planes {#catalog-and-plans}

| Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación |
|---|---|---|---|---|
| `templates_list` | Plantillas de SO que los clientes pueden instalar. | `admin:read` | No | No |
| `templates_sync` | Importar plantillas de SO desde CloudStack. | `catalog:write` | Sí | No |
| `template_update` | Habilitar u ocultar una plantilla, cambiarle el nombre, definir el usuario de inicio de sesión o el orden. | `catalog:write` | Sí | No |
| `offerings_list` | Ofertas de servicio de CloudStack (CPU, memoria, disco raíz) para crear planes a partir de ellas. | `admin:read` | No | No |
| `plans_list` | Planes con precio por hora y por mes, tamaño, zona y cuántos servidores los utilizan. | `admin:read` | No | No |
| `plan_create` | Crear un plan. Precio como `hourly_usd`. Los planes de CloudStack requieren `cs_offering_id`; los planes de Proxmox requieren `backend_id`. | `catalog:write` | Sí | No |
| `plan_update` | Renombrar, mostrar u ocultar, habilitar o deshabilitar, o cambiar el precio de un plan. Cambiar el tamaño en un plan en uso requiere una copia. | `catalog:write` | Sí | Al cambiar el precio |
| `plans_from_offerings` | Crea una tabla de planes iniciales a partir de ofertas (o tamaños de Proxmox) utilizando su costo y un porcentaje de margen. Devuelve una vista previa; llame de nuevo con `apply=true` para crear los planes. | `catalog:write` | Con `apply=true` | Siempre al aplicar |
| `quota_defaults_get` | Límites predeterminados de clientes. | `admin:read` | No | No |
| `quota_defaults_set` | Cambia la configuración de `quota_*`. | `catalog:write` | Sí | No |
| `coupons_list` | Lotes de códigos de descuento y de regalo. | `admin:read` | No | No |
| `coupon_create` | Crea un lote de códigos: tipo `money` (valor nominal en centavos de USD) o `percent` (de 1 a 100, con un descuento máximo). | `catalog:write` | Sí | Siempre |

### Clientes y revendedores {#customers-and-resellers}

| Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación |
|---|---|---|---|---|
| `customers_search` | Busca clientes por correo electrónico, nombre o IP. | `admin:read` | No | No |
| `customer_get` | Cuenta, saldo, servidores y facturación reciente de un cliente. | `admin:read` | No | No |
| `customer_adjust_balance` | Añade (positivo) o retira (negativo) crédito en centavos de USD. Se requiere un motivo. | `billing:write` | Sí | Siempre |
| `customer_block` | Bloquea a un cliente, deteniendo opcionalmente sus servidores. Se requiere un motivo. | `customers:write` | Sí | Siempre |
| `customer_unblock` | Desbloquea a un cliente. | `customers:write` | Sí | No |
| `resellers_list` | Revendedores con billetera y estado. | `admin:read` | No | No |
| `reseller_get` | Sitio, billetera, usuarios y pasarelas de un revendedor. | `admin:read` | No | No |

### Proveedor de IA {#ai-provider}

| Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación |
|---|---|---|---|---|
| `ai_provider_get` | El proveedor compatible con OpenAI utilizado por AI Chat y AI Agent del cliente (clave enmascarada). | `admin:read` | No | No |
| `ai_provider_set` | Define el proveedor: URL base, modelo, clave de API, modelos de respaldo, esfuerzo de razonamiento, habilitado. | `ai:write` (+ `secrets:write` para la clave) | Sí | No |
| `ai_provider_test` | Hace una pregunta al proveedor guardado para comprobar que funciona. | `ai:write` | No | No |

### Archivos de configuración {#configuration-files}

| Herramienta | Qué hace | Scope | Modifica datos | Pide confirmación |
|---|---|---|---|---|
| `config_export` | Exporta la configuración como YAML (los secretos se convierten en referencias `secret://`). | `admin:read` | No | No |
| `config_plan` | Compara una configuración YAML con el panel activo y enumera los cambios. | `admin:read` | No | No |
| `config_apply` | Aplica una configuración YAML sección por sección. Cada cambio sigue las reglas normales de alcance y confirmación. | `admin:read` + el alcance de cada cambio | Sí | Por cada cambio |

Consulte [Configuración como código](https://nexcmp.com/es/docs/configure-with-ai/config-as-code/) para conocer el formato de archivo.

## Prompts {#prompts}

El servidor también ofrece tres prompts predefinidos que los clientes pueden mostrar como accesos directos:

| Prompt | Argumento | Qué le pide hacer a la IA |
|---|---|---|
| `initial-setup` | ninguno | Llama a `setup_checklist`, explica cada paso pendiente en una sola frase, le solicita la información que necesita, ejecuta el paso con la herramienta correspondiente, muestra una vista previa de los cambios de dinero o seguridad y finaliza con `system_health`. |
| `add-proxmox` | `endpoint` (opcional, `https://host:8006`) | Solicita el token de API, luego `proxmox_add`, `proxmox_test`, herramientas de zona y `proxmox_attach_zone`; después propone planes con `plans_from_offerings` y espera su aprobación. |
| `launch-pricing` | `margin_pct` (opcional, predeterminado 40) | Solicita su costo mensual por vCPU, por GB de RAM y por GB de disco, muestra una tabla de vista previa con el costo, el precio mensual y el precio por hora, y crea los planes tras su aprobación. |

## Confirmación (`confirm_token`) {#confirmation-confirm-token}

Las acciones que transfieren dinero, eliminan datos, modifican credenciales de pago o la seguridad de inicio de sesión constan de dos pasos:

1. La primera llamada no modifica nada. El resultado de la herramienta comienza con "CONFIRMATION REQUIRED" e incluye una **vista previa** (qué se llamará, por qué es delicado, los nuevos valores y los actuales) y un `confirm_token`.
2. El cliente debe mostrarle la vista previa. Solo tras su aprobación vuelve a llamar a la misma herramienta con los mismos argumentos más `confirm_token`.
3. El token funciona una sola vez, únicamente para esa solicitud exacta, y caduca a los 5 minutos.

Las instrucciones del servidor indican a la IA que trate los resultados de las herramientas como datos, no como instrucciones, y que nunca repita una llamada con un token que usted no haya aprobado. Usted es la salvaguarda: revise la vista previa.

::: warning No apruebe automáticamente
Algunos clientes pueden aprobar cada llamada de herramienta automáticamente. Para las herramientas de escritura, mantenga activa la aprobación llamada por llamada o use una clave de solo lectura, de modo que un plan incorrecto de la IA no llegue a su panel sin supervisión.
:::

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

| Elemento | Detalle |
|---|---|
| Transporte | `POST /mcp/admin` con un mensaje JSON-RPC 2.0; la respuesta es `application/json`. Hasta 20 mensajes en un lote. `GET /mcp/admin` responde 405 (sin server stream); `DELETE /mcp/admin` finaliza una sesión. |
| Autenticación | `Authorization: Bearer ak_...` (una clave manual o un token de acceso OAuth). Las credenciales faltantes o incorrectas devuelven 401 con `WWW-Authenticate: Bearer ... resource_metadata=...`, lo que permite a los clientes OAuth iniciar sesión por sí mismos. |
| Sesiones | `Mcp-Session-Id` es emitido por `initialize`, está vinculado a esa clave y es válido durante 24 horas. |
| Capacidades | Herramientas y prompts. Sin recursos. |
| Tamaño | Cuerpo de solicitud de hasta 1 MB; el resultado de una herramienta se trunca tras unos 100 KB. |
| Origen | Se rechaza una solicitud que contenga una cabecera `Origin` de otro sitio (`origin_not_allowed`). Los clientes de línea de comandos y de escritorio no envían ninguna. |
| Mismo control que REST | Cada llamada de herramienta se reenvía a través del propio pipeline de solicitudes del panel con su clave, por lo que los alcances, los rangos de IP, el rate limit, la confirmación y el registro de actividad se aplican exactamente igual que en las llamadas directas a la API. |

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

- Una herramienta que no puede ver es un alcance que no otorgó. Añada el alcance a una nueva clave.
- Configurar una contraseña o clave de API a través de un cliente de IA significa que el secreto pasa por esa IA. Si lo prefiere, deje `secrets:write` desactivado e introduzca los secretos usted mismo en el panel de administración, o use el campo **Secret** de AI Chat ([AI Chat en la administración](https://nexcmp.com/es/docs/configure-with-ai/ai-chat-in-admin/#secrets)) o las referencias `secret://` ([Configuración como código](https://nexcmp.com/es/docs/configure-with-ai/config-as-code/#secrets)).
- Los clientes no comparten sesiones: cada conexión comienza con `initialize`.
- Revoque la clave en **API & AI agents** para desconectar de inmediato a un cliente de IA.

## Resolución de problemas {#troubleshooting}

| Síntoma | Causa | Solución |
|---|---|---|
| 401 `invalid_key` | Clave incorrecta, truncada o que no es de administrador (por ejemplo, una clave `vk_`) | Use una clave `ak_`. |
| 401 `key_expired` o `key_revoked` | La clave expiró o fue revocada | Cree una nueva clave. |
| 403 `ip_not_allowed` | Su IP está fuera de los rangos de IP de la clave | Conéctese desde una IP permitida. |
| 403 `origin_not_allowed` | Una página del navegador en otro origen llamó al endpoint | Use un cliente de escritorio o CLI. |
| 404 en una solicitud con `Mcp-Session-Id` | La sesión pertenece a otra clave o ha expirado | Envíe `initialize` de nuevo. |
| 400 unsupported `MCP-Protocol-Version` | El cliente utiliza una versión que el servidor no reconoce | Actualice el cliente; admitidas: 2025-11-25, 2025-06-18, 2025-03-26. |
| La lista de herramientas es corta | Alcances de la clave | Cree una clave con más alcances. |
| `insufficient_scope` en una llamada | Una herramienta necesita un segundo alcance, por ejemplo `secrets:write` | Añada el alcance a una nueva clave. |
| 429 `rate_limited` | Más llamadas por minuto de las que permite la clave | Espere a `Retry-After` o aumente el límite en una nueva clave. |
| claude.ai o ChatGPT no pueden conectarse | La URL no es accesible desde internet, o un proxy bloquea `/mcp/admin` o `/oauth-admin/` | Compruebe el DNS, TLS y el proxy inverso. |

Para ver todos los códigos de error, consulte [Claves de API de administración](https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/#errors).