Conectar con una clave de API de MCP

El endpoint remoto permite que un asistente de IA se conecte directamente a tu instancia de Gigantics. No hay nada que instalar: activas el endpoint, creas una clave y pegas un comando o un fragmento de configuración en tu asistente.

Una clave de API de MCP actúa como el usuario Root que la creó, con acceso a toda la instancia. Trátala como una contraseña.

Antes de empezar

Debes ser un usuario Root. Solo los usuarios Root pueden abrir los Ajustes Globales y crear claves de MCP.
Tu instancia debe servirse por HTTPS, directamente o detrás de un proxy que termine TLS (consulta Configuración de Nginx). El http:// sin cifrar solo se acepta desde la propia máquina de la instancia.
Tu asistente debe poder conectarse a un servidor MCP por HTTP y enviar una cabecera Authorization personalizada. Claude Code, Cursor y VS Code pueden.

Paso 1: Activar el endpoint

Pulsa tu avatar y selecciona Ajustes Globales.
Abre la sección MCP de la barra lateral.
Activa Endpoint MCP remoto (Remote MCP endpoint).

La página muestra la dirección que debe usar tu asistente, por ejemplo https://gig.example.com/mcp. Pulsa Copiar para copiarla.

┌─────────────────────────────────────────────────────────────────┐
│ MCP                                                 [Crear clave]│
│ Permite que clientes MCP remotos administren esta instancia      │
├─────────────────────────────────────────────────────────────────┤
│ [ON]  Endpoint MCP remoto                                        │
│ [ https://gig.example.com/mcp                        ] [Copiar]  │
├─────────────────────────────────────────────────────────────────┤
│ Nombre      │ Clave         │ Actúa como │ Herram. destructivas │
│ Claude Code │ gigmcp_4f8a_… │ Ana        │ Aprueba una persona  │
└─────────────────────────────────────────────────────────────────┘

El endpoint está desactivado por defecto. Mientras lo está, /mcp no existe en tu servidor.

Si abres la página por http:// sin cifrar desde otra máquina, la página te avisa: el endpoint rechaza el HTTP sin cifrar, así que sirve primero la instancia por HTTPS.

Paso 2: Crear una clave

Pulsa Crear clave (Create key).
Rellena el formulario:

Campo	Descripción
Nombre	Un nombre que te diga dónde se usa la clave, por ejemplo Claude Code en mi portátil (obligatorio, hasta 100 caracteres)
Caduca	30 días, 90 días (por defecto), 1 año o Nunca. Una clave que caduca deja de funcionar en esa fecha
Permitir modo agente	Desactivado por defecto. Si está desactivado, una persona aprueba cada llamada a una herramienta destructiva. Lee Aprobaciones y seguridad antes de activarlo

Pulsa Crear clave.

Gigantics muestra la nueva clave, que tiene el aspecto gigmcp_4f8a21c9_…, junto con comandos de conexión listos para usar.

La clave se muestra una sola vez. No se puede recuperar cuando cierras la ventana. Cópiala y guárdala en un gestor de contraseñas antes de pulsar Sí, he copiado la clave y la he guardado.

Puedes tener hasta 20 claves de API de MCP. Crea una clave por asistente o por persona, para poder eliminar una sin afectar a las demás.

Paso 3: Conectar tu asistente

Claude Code

Ejecuta este comando en tu terminal. La ventana del paso 2 ya lo muestra con tu dirección y tu clave:

claude mcp add --transport http gigantics https://gig.example.com/mcp \
  --header "Authorization: Bearer gigmcp_..."

Otros clientes MCP (Cursor, VS Code, ...)

Añade esto a la configuración MCP de tu cliente:

{
  "mcpServers": {
    "gigantics": {
      "type": "http",
      "url": "https://gig.example.com/mcp",
      "headers": { "Authorization": "Bearer gigmcp_..." }
    }
  }
}

El lugar y el formato exactos de ese fichero dependen del cliente. Consulta su documentación de MCP si no acepta este fragmento tal cual.

Algunos asistentes alojados (por ejemplo, la versión web de un asistente) solo pueden conectarse con OAuth y no pueden enviar una cabecera Authorization fija. Todavía no pueden usar claves de API de MCP.

Paso 4: Probarlo

Pregunta a tu asistente:

"Comprueba el estado de mi instancia de Gigantics."

Debería responder con la versión del servidor y los métodos de inicio de sesión en uso. Si lo hace, estás conectado. La columna Último uso de la lista de claves mostrará ahora la hora de la petición.

Gestionar las claves

La lista de claves muestra una fila por clave:

Columna	Descripción
Nombre	El nombre que diste a la clave
Clave	El comienzo de la clave, `gigmcp_<prefijo>_…`, para reconocerla. El resto no se vuelve a mostrar
Actúa como	El usuario Root que creó la clave
Herramientas destructivas	Aprueba una persona (por defecto) o Modo agente (naranja)
Caduca	Cuándo deja de funcionar la clave, Nunca, o Caducada si ya lo hizo
Último uso	Hace cuánto se usó. Pasa el ratón para ver la dirección IP
Creada el	Cuándo se creó la clave

Para eliminar una clave, abre el menú ⋮ de su fila y selecciona Eliminar, y confirma con Sí, eliminar. Los clientes que la usan dejan de funcionar al instante y sus sesiones abiertas se cierran.

Una clave también deja de funcionar, sin eliminarse, cuando:

caduca,
el usuario como el que actúa ya no es Root o se elimina,
desactivas Endpoint MCP remoto. Vuelve a activarlo y las claves funcionan de nuevo.

La creación y eliminación de claves queda registrada en los Eventos con el origen Auth. La clave en sí nunca se registra.

Diferencias con el servidor local

El endpoint remoto tiene las mismas herramientas, aprobaciones y vistas que el servidor local, con estas diferencias:

Sin herramientas de mantenimiento. Ejecutar migraciones, comprobar los procesos del servidor y reiniciarlo se ejecutarían en la máquina del servidor, así que no se ofrecen. Hazlo desde el equipo de la instancia.
La clave decide el modo de aprobación. No hay un interruptor para todo el servidor: una clave es Aprueba una persona o Modo agente.
Cuando se rechaza una petición, el asistente te dirige a la interfaz de Gigantics en lugar de al comando gig admin.

Cómo está protegido el endpoint

Protección	Qué significa para ti
Fuerte y guardada con hash	Las claves tienen 256 bits aleatorios. Gigantics solo guarda un hash, así que ni quien tenga acceso a la base de datos puede leerlas
Solo en la cabecera	La clave se lee de la cabecera `Authorization`, nunca de la URL, por lo que no acaba en los logs
HTTPS obligatorio	Se rechazan las peticiones por HTTP sin cifrar desde otras máquinas
Límite de fuerza bruta	Tras 10 claves incorrectas desde la misma dirección en 5 minutos, esa dirección se bloquea durante un tiempo (HTTP 429)
Sin navegadores	Se rechazan las peticiones que vienen de una página web de otro sitio. Los asistentes nativos no se ven afectados
Mismas comprobaciones de permisos	El endpoint ejecuta cada llamada como el usuario Root de la clave, con las comprobaciones de permisos normales. La clave no se acepta en ningún otro sitio (por ejemplo, `/graphql`)
Sesiones	Una conexión queda ligada a su clave, se cierra tras 30 minutos sin actividad, y la instancia admite hasta 10 por clave

Solución de problemas

Qué ves	Causa	Solución
404	Endpoint MCP remoto está desactivado	Actívalo en Ajustes Globales → MCP
401 Invalid MCP API key	La clave es incorrecta, está eliminada o caducada, o su propietario ya no es Root	Revisa la clave y su columna Caduca, o crea una nueva
401 An MCP API key is required	El cliente no envía la cabecera `Authorization`	Revisa los `headers` de la configuración de tu cliente
403 needs HTTPS	Se accede a la instancia por HTTP sin cifrar desde otra máquina	Usa la dirección `https://`, o pon la instancia detrás de un proxy TLS que envíe `X-Forwarded-Proto: https`
403 Origin not allowed	La petición viene de una página web de otro sitio	Usa un asistente nativo en lugar de una herramienta en el navegador
429	10 claves incorrectas desde la misma dirección	Espera el tiempo indicado en la cabecera `Retry-After` y corrige la clave
El cliente se reconecta o recibe un 404 en peticiones posteriores	La instancia ejecuta varios workers web (`gig start --web=N`) y la petición llegó a otro	Ejecuta un solo worker web, o pide a tu administrador que dirija cada cliente al mismo worker