Conexión mediante MCP

Las integraciones de máquina se autentican como cuenta de servicio mediante la concesión OAuth client_credentials o — para clientes que solo pueden enviar un encabezado fijo — mediante una clave de API estática. Sin navegador, sin sesión de usuario, sin consentimiento interactivo.

1. Crear una cuenta de servicio

Un administrador lo hace desde Admin → Cuentas de servicio:

1. Introduzca un nombre para mostrar que identifique la integración: "Jira Sync", no "api". Aparece en el historial de auditoría.
2. Pulse Crear. El secreto de cliente y la clave de API se muestran una sola vez; cópielos de inmediato. Si se pierden, use Volver a emitir secreto — ninguno de los dos puede recuperarse.

El id de la cuenta de servicio es el client_id y es seguro guardarlo en la configuración. El secreto no: trátelo como una contraseña.

2. Concederle acceso a un Brain

Una cuenta de servicio nueva puede autenticarse, pero no ve nada. El acceso lo concede por Brain un administrador, desde Admin → Brains → el Brain → su sección de acceso de cuentas de servicio. Tenga en cuenta que esta es la página de Brain de administración: la página de Brain para usuarios gestiona el acceso de usuarios y grupos, no el de cuentas de servicio.

Elija la cuenta de servicio y seleccione un nivel:

Conceda lo mínimo necesario. Un agente que solo responde preguntas debería ser read: así, un intento de inyección de prompt en el contenido recuperado no puede dar lugar a escrituras.

3. Obtener un token de acceso

POST /brain/{brain_id}/token. Se admite tanto formato de formulario como JSON. El token de acceso es un JWT de tipo bearer válido durante 1 hora; el token de actualización dura 30 días.

curl -X POST https://hive.example.com/brain/$BRAIN_ID/token \
  -d grant_type=client_credentials \
  -d client_id=$HIVE_CLIENT_ID \
  -d client_secret=$HIVE_CLIENT_SECRET

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOi..."
}

Para rotar sin volver a enviar el secreto, envíe grant_type=refresh_token con el refresh_token. Los tokens de actualización rotan al usarse: guarde el nuevo.

Los tokens de actualización están vinculados al secreto actual de la cuenta. Después de volver a emitir el secreto, o cuando caduca, una actualización devuelve invalid_grant: solicite un token nuevo con grant_type=client_credentials usando el secreto actual. Mantenga el secreto de cliente disponible para su integración; un token de actualización por sí solo no basta para recuperar el acceso.

4. Llamar a una herramienta

El punto de conexión MCP es POST /brain/{brain_id}/mcp, JSON-RPC 2.0 sobre el transporte streamable-HTTP. Envíe el token de acceso como encabezado bearer y acepte ambos tipos de contenido:

curl -X POST https://hive.example.com/brain/$BRAIN_ID/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "aiqbee_search",
      "arguments": {"query": "what did we decide about rate limiting?"}
    }
  }'

tools/list devuelve el conjunto completo de herramientas con sus esquemas, útil para generar sus definiciones de herramientas mediante programación en lugar de codificarlas a mano.

Claves de API

Algunas plataformas de agentes no pueden realizar un intercambio de token y solo pueden adjuntar un encabezado fijo a cada solicitud. Para ellas, una cuenta de servicio también incluye una clave de API, emitida junto con el secreto de cliente y con la misma caducidad. Prefiera las credenciales de cliente (arriba) siempre que su cliente pueda usarlas.

Envíe la clave en X-Api-Key a cualquier punto de conexión MCP, https://<hive>/brain/<brain-id>/mcp. No hace falta solicitar un token:

X-Api-Key: <api-key>

curl -X POST https://<hive>/brain/<brain-id>/mcp \
  -H "X-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

• La clave concede exactamente lo que concede la cuenta de servicio — el mismo acceso a los Brains, las mismas capas de permisos, el mismo requisito allow_mcp_editing.
• La clave debe enviarse en X-Api-Key. Enviarla como token Authorization: Bearer se rechaza, con un mensaje que lo indica.
• Un 401 significa que la clave es incorrecta, está revocada o ha caducado — sustitúyala. Un 503 con Retry-After significa que el Hive no pudo verificar la clave en ese momento — reintente; no vuelva a emitir nada.
• La clave comparte la caducidad del secreto de cliente y se rota cada vez que se vuelve a emitir el secreto.
• Las cuentas de servicio creadas antes de que existieran las claves de API obtienen una clave en su próximo Volver a emitir secreto.

Opcionalmente, intercambie la clave por un token de acceso: POST /brain/<brain-id>/token con grant_type=api_key y api_key=<api-key> devuelve un token de acceso de 1 hora y ningún token de actualización.

Un token obtenido con grant_type=api_key sigue siendo válido hasta que caduca (como máximo 1 hora), incluso después de volver a emitir la clave, mientras que una clave enviada directamente en X-Api-Key deja de funcionar en la siguiente solicitud.

VS Code (SSH remoto / sin interfaz)

Cuando el inicio de sesión OAuth no puede abrir un navegador, ponga la clave en mcp.json como encabezado y manténgala fuera del archivo con un aviso oculto:

{
  "inputs": [
    { "id": "hive-api-key", "type": "promptString",
      "description": "Hive API key", "password": true }
  ],
  "servers": {
    "aiqbee-hive": {
      "type": "http",
      "url": "https://<hive>/brain/<brain-id>/mcp",
      "headers": { "X-Api-Key": "${input:hive-api-key}" }
    }
  }
}

Conexión desde Azure AI Foundry

Foundry ofrece varios métodos de autenticación para herramientas MCP. Solo uno es adecuado para una cuenta de servicio.

1. En Hive, cree una cuenta de servicio en Administración → Cuentas de servicio y copie la clave de API mostrada al crearla. Use una cuenta de servicio por integración para poder revocarla sin afectar a nada más.
2. Concédale acceso al Brain que quiera que use el agente (paso 2 anterior). Las cuentas de servicio no obtienen acceso de forma implícita.
3. En el portal de Foundry, abra su proyecto y vaya a Build → Tools, luego a Add tool → Custom → Model Context Protocol.
4. Complete la conexión: punto de conexión https://<hive>/brain/<brain-id>/mcp, Autenticación Key-based, Nombre de la credencial X-Api-Key, Valor de la credencial su clave de API. Luego seleccione Connect.

Conviene saber

• Cualquier persona con acceso al proyecto de Foundry puede leer una credencial almacenada en una conexión del proyecto. Use una cuenta de servicio de privilegios mínimos por integración.
• La clave deja de funcionar en la fecha de caducidad del secreto. Programe un recordatorio antes — Foundry almacena el valor de forma estática, así que alguien tiene que pegar uno nuevo.
• Requerir aprobación es always por defecto. Un never global también aprueba automáticamente las escrituras y eliminaciones: indique más bien las herramientas de solo lectura y deje todo lo que escribe en always.
• Use el punto de conexión específico del Brain, de modo que el parámetro brain_id desaparezca de los esquemas de herramientas y el modelo tenga menos margen de error.

Un cliente mínimo en Python

La mayoría de los SDK de MCP se encargan de esto automáticamente. Si lo configura manualmente, toda la superficie es así de reducida:

import os, httpx

BASE     = os.environ["HIVE_BASE_URL"]
BRAIN_ID = os.environ["HIVE_BRAIN_ID"]


class Hive:
    """Thin Hive MCP client. Fetches a token lazily and retries once on 401."""

    def __init__(self) -> None:
        self._client = httpx.Client(timeout=30)
        self._token: str | None = None

    def _get_token(self) -> str:
        r = self._client.post(
            f"{BASE}/brain/{BRAIN_ID}/token",
            data={
                "grant_type": "client_credentials",
                "client_id": os.environ["HIVE_CLIENT_ID"],
                "client_secret": os.environ["HIVE_CLIENT_SECRET"],
            },
        )
        r.raise_for_status()
        return r.json()["access_token"]

    def call(self, tool: str, **arguments: object) -> dict:
        if self._token is None:
            self._token = self._get_token()

        def _post() -> httpx.Response:
            return self._client.post(
                f"{BASE}/brain/{BRAIN_ID}/mcp",
                headers={
                    "Authorization": f"Bearer {self._token}",
                    "Accept": "application/json, text/event-stream",
                },
                json={
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/call",
                    "params": {"name": tool, "arguments": arguments},
                },
            )

        response = _post()
        if response.status_code == 401:      # token expired mid-session
            self._token = self._get_token()
            response = _post()
        response.raise_for_status()
        return response.json()


hive = Hive()
print(hive.call("aiqbee_search", query="rate limiting decision"))

Solución de problemas