Connexion via MCP

Les intégrations machine s'authentifient en tant que compte de service via le flux OAuth client_credentials ou — pour les clients qui ne peuvent envoyer qu'un en-tête fixe — via une clé API statique. Aucun navigateur, aucune session utilisateur, aucun consentement interactif.

1. Créer un compte de service

Un administrateur effectue cette opération depuis Admin → Comptes de service :

1. Saisissez un nom affiché qui identifie l’intégration — « Jira Sync », et non « api ». Il apparaît dans l’historique d’audit.
2. Cliquez sur Créer. Le secret client et la clé API ne sont affichés qu'une seule fois ; copiez-les immédiatement. S'ils sont perdus, utilisez Réémettre le secret — ni l'un ni l'autre ne peut être récupéré.

L'identifiant du compte de service est le client_id, et il peut être stocké sans risque dans la configuration. Le secret, non — traitez-le comme un mot de passe.

2. Lui accorder l’accès à un brain

Un nouveau compte de service peut s’authentifier mais ne voit rien. L’accès est accordé par brain par un administrateur, depuis Admin → Brains → le brain → sa section d’accès des comptes de service. Notez qu’il s’agit de la page de brain admin : la page de brain côté utilisateur gère l’accès des utilisateurs et des groupes, pas celui des comptes de service.

Choisissez le compte de service et un niveau :

Accordez le minimum nécessaire. Un agent qui ne fait que répondre à des questions doit être en read — ainsi, une tentative d’injection de prompt dans le contenu récupéré ne peut pas conduire à des écritures.

3. Obtenir un jeton d’accès

POST /brain/{brain_id}/token. Le format formulaire et le JSON fonctionnent tous deux. Le jeton d’accès est un JWT bearer valable 1 heure ; le jeton d’actualisation dure 30 jours.

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..."
}

Pour renouveler sans renvoyer le secret, envoyez grant_type=refresh_token avec le refresh_token. Les jetons d'actualisation sont renouvelés à l'usage — conservez le nouveau.

Les jetons d’actualisation sont liés au secret actuel du compte. Après la réémission du secret, ou dès son expiration, une actualisation renvoie invalid_grant — demandez un nouveau jeton avec grant_type=client_credentials en utilisant le secret actuel. Gardez le secret client à la disposition de votre intégration ; un jeton d’actualisation seul ne suffit pas pour récupérer l’accès.

4. Appeler un outil

Le point de terminaison MCP est POST /brain/{brain_id}/mcp, JSON-RPC 2.0 sur le transport streamable-HTTP. Envoyez le jeton d'accès dans un en-tête bearer et acceptez les deux types de contenu :

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 renvoie l’ensemble complet des outils avec leurs schémas — utile pour générer vos définitions d’outils par programmation plutôt que de les écrire en dur.

Clés API

Certaines plateformes d'agents ne peuvent pas effectuer d'échange de jeton et ne peuvent joindre qu'un en-tête fixe à chaque requête. Pour celles-ci, un compte de service possède aussi une clé API, émise avec le secret client et partageant son expiration. Privilégiez les identifiants client (ci-dessus) partout où votre client peut les utiliser.

Envoyez la clé dans X-Api-Key vers n'importe quel point de terminaison MCP, https://<hive>/brain/<brain-id>/mcp. Aucune demande de jeton n'est nécessaire :

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 clé accorde exactement ce que le compte de service accorde — le même accès aux Brains, les mêmes couches d'autorisations, la même exigence allow_mcp_editing.
• La clé doit être envoyée dans X-Api-Key. L'envoyer comme jeton Authorization: Bearer est refusé, avec un message l'indiquant.
• Un 401 signifie que la clé est incorrecte, révoquée ou expirée — remplacez-la. Un 503 avec Retry-After signifie que le Hive n'a pas pu vérifier la clé à ce moment-là — réessayez ; ne réémettez rien.
• La clé partage l'expiration du secret client et est renouvelée chaque fois que le secret est réémis.
• Les comptes de service créés avant l'existence des clés API reçoivent une clé à leur prochain Réémettre le secret.

En option, échangez la clé contre un jeton d'accès : POST /brain/<brain-id>/token avec grant_type=api_key et api_key=<api-key> renvoie un jeton d'accès valable 1 heure et aucun jeton d'actualisation.

Un jeton obtenu avec grant_type=api_key reste valide jusqu’à son expiration (1 heure au maximum), même après la réémission de la clé, tandis qu’une clé envoyée directement dans X-Api-Key cesse de fonctionner dès la requête suivante.

VS Code (SSH distant / sans interface)

Lorsque la connexion OAuth ne peut pas ouvrir de navigateur, placez la clé dans mcp.json comme en-tête et gardez-la hors du fichier grâce à une invite masquée :

{
  "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}" }
    }
  }
}

Connexion depuis Azure AI Foundry

Foundry propose plusieurs méthodes d'authentification pour les outils MCP. Une seule convient à un compte de service.

1. Dans Hive, créez un compte de service sous Administration → Comptes de service et copiez la clé API affichée à la création. Utilisez un compte de service par intégration afin de pouvoir le révoquer sans affecter le reste.
2. Accordez-lui l'accès au Brain que l'agent doit utiliser (étape 2 ci-dessus). Les comptes de service n'ont aucun accès implicite.
3. Dans le portail Foundry, ouvrez votre projet et allez dans Build → Tools, puis Add tool → Custom → Model Context Protocol.
4. Renseignez la connexion : point de terminaison https://<hive>/brain/<brain-id>/mcp, Authentification Key-based, Nom de l'identifiant X-Api-Key, Valeur de l'identifiant votre clé API. Sélectionnez ensuite Connect.

À savoir

• Toute personne ayant accès au projet Foundry peut lire un identifiant stocké dans une connexion de projet. Utilisez un compte de service à privilèges minimaux par intégration.
• La clé cesse de fonctionner à la date d'expiration du secret. Programmez un rappel avant cette date — Foundry stocke la valeur de façon statique, il faut donc que quelqu'un en colle une nouvelle.
• Exiger une approbation vaut par défaut always. Un never global approuve aussi automatiquement les écritures et les suppressions : nommez plutôt les outils en lecture seule et laissez tout ce qui écrit sur always.
• Utilisez le point de terminaison propre au Brain, afin que le paramètre brain_id disparaisse des schémas d'outils et que le modèle ait moins de risques de se tromper.

Un client Python minimal

La plupart des SDK MCP s'en chargent pour vous. Si vous le câblez à la main, toute la surface est aussi réduite que ceci :

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"))

Dépannage