Guide — Gouvernance MCP multi-instances

Ce guide s'adresse à l'administrateur de l'écosystème Telaria (Mathieu) qui émet et révoque les tokens MCP pour chaque instance Claude.

Principe : 1 token par rôle d'instance

Chaque instance Claude de l'écosystème est un client MCP distinct avec un token opaque différent. On ne partage pas de token entre instances : en cas de compromission ou de fin de session d'un rôle, la révocation est ciblée et n'impacte pas les autres.

Les scopes sont différenciés selon l'accès légitime de chaque rôle :

Scope 2D : un client doit avoir à la fois le scope tool:<name> ET le scope project:<slug> pour exécuter un outil. L'absence de l'un ou l'autre bloque avec FORBIDDEN_TOOL ou FORBIDDEN_PROJECT.

Émettre un token pour une nouvelle instance

Le seed crée le tenant, le projet (s'il n'existe pas) et l'ApiClient en BDD, puis affiche le token brut une seule fois.

# Dans telaria-app (qui héberge le bundle MCP)
php bin/console app:mcp:seed \
  --tenant="telaria" \
  --project="telaria-doc" \
  --root="/var/www/telaria/docs" \
  --scopes="tool:list_docs tool:read_doc tool:search_docs project:telaria-doc" \
  --label="atlas-tlr-doc"

Le token affiché est la valeur opaque à reporter dans .mcp.json de l'instance. En BDD, seul son hash SHA-256 est stocké — il est impossible de le retrouver après coup. Le noter immédiatement.

Paramètres :

Reporter le token dans l'instance

Une fois le token émis, le reporter dans le .mcp.json du repo de travail de l'instance (cf. tuto brancher-mcp-claude-code.md) :

{
  "mcpServers": {
    "tlr-mcp": {
      "command": "php",
      "args": ["C:/src/telaria-app/bin/console", "mcp:serve"],
      "env": {
        "MCP_TOKEN": "le-token-opaque-recopié-ici"
      }
    }
  }
}

Le .mcp.json est versionné — mais sans la valeur du token si le repo est public. Dans ce cas, laisser la valeur vide ou en placeholder et documenter la procédure de renseignement manuel dans le README ou CLAUDE.md du repo.

Révoquer un token

Si une instance est compromise, si un rôle change, ou en fin de session longue durée :

# Révoquer par label (ApiClient en BDD)
php bin/console app:mcp:revoke --label="atlas-tlr-doc"

# Ou directement en BDD
UPDATE mcp_api_clients SET revoked = 1 WHERE label = 'atlas-tlr-doc';

Après révocation, le token renvoie TOKEN_REVOKED (-32000) à la prochaine tentative d'appel. Re-seed pour émettre un nouveau token si le rôle continue.

Audit des usages

La table mcp_tool_audit_log trace chaque appel outil :

SELECT label, tool_name, status, error_code, timestamp
FROM mcp_tool_audit_log
JOIN mcp_api_clients ON api_client_id = mcp_api_clients.id
WHERE tenant_id = (SELECT id FROM mcp_tenants WHERE name = 'telaria')
ORDER BY timestamp DESC
LIMIT 50;

Colonnes utiles :

Rotation périodique des tokens

Il n'y a pas de rotation automatique en V1. La politique recommandée :

• Tokens de dev (instances atlas, leadtech, chef) : durée de vie indéfinie, révocation manuelle si incident.
• Token de démo (Claude Desktop vitrine) : re-seed avant chaque démo publique significative.
• Token VPS (HTTP Streamable V1.1) : rotation mensuelle recommandée dès que le transport distant est en production.

Pour aller plus loin

• Tuto Claude Code CLI : brancher-mcp-claude-code.md
• Tuto Claude Desktop + Cursor : brancher-mcp-claude-desktop-cursor.md
• Déploiement VPS : mcp-vps.md
• Spec auth + scopes : bundles/tlr-mcp/tlr-mcp-securite-conformite.md