Aller au contenu principal
Dernière mise à jour le

Tutoriel : contrôlez l'accès de l'agent de codage au MCP GitHub

Dans ce tutoriel, vous régissez l'accès d'un agent de codage à GitHub à l'aide d'Unity Catalog et de l'AI Gateway. Supposons que votre équipe utilise un agent de codage tel que Claude Code ou Cursor pour lire les repository et les pull requests, mais que vous souhaitiez bloquer les opérations d'écriture et auditer chaque appel d'outil.

Vous utilisez le system.ai.github MCP Service fourni par Databricks, de sorte que vous n'hébergez ni n'enregistrez de serveur MCP et ne créez pas de connexion Unity Catalog. Vous attachez une politique de service intégrée pour bloquer les opérations d'écriture, accorder l'accès à votre équipe, connecter un agent de codage et confirmer que chaque appel d'outil est enregistré.

Prérequis​

  • Un Workspace activé pour Unity Catalog. Consultez Se familiariser avec Unity Catalog.

  • Les fonctionnalités de la version bêta de Unity Gateway sont activées pour votre compte. Un administrateur de compte peut les activer depuis la page Aperçus de la console du compte. Consultez Gérer les aperçus Databricks.

  • Les privilèges suivants sur le service intégré system.ai.github:

    • MANAGE, pour attacher une politique de service.
    • EXECUTE, pour appeler le service et pour accorder l'accès à d'autres.

  • Pour utiliser l'API REST à l'étape 1, authentifiez la CLI Databricks auprès de votre workspace.

  • Si votre workspace utilise une politique réseau serverless restreinte, un administrateur du compte doit autoriser les destinations requises par le service GitHub MCP.

Trouver les domaines requis

Pour trouver les domaines requis, connectez votre agent à l'étape 3 et essayez un outil GitHub en lecture seule. Si la politique de réseau bloque l'appel, l'erreur indique le nom du domaine bloqué (Access to <fqdn> is denied because of serverless network policy). Un administrateur de compte peut ajouter ce domaine à la section Domaines autorisés dans la politique de réseau et réessayer.

Si l’appel échoue toujours, consultez les logs de refus du réseau sortant après un autre appel de test. Remplacez <workspace-id> par votre ID du workspace. Le schéma system.access doit être activé pour query la table.

SQL
SELECT event_time, destination
FROM system.access.outbound_network
WHERE workspace_id = '<workspace-id>'
  AND destination_type = 'DNS'
  AND access_type = 'DROP'
  AND event_time >= current_timestamp() - INTERVAL 15 MINUTES
ORDER BY event_time DESC;

La table n'identifie pas le service MCP ; comparez donc event_time avec l'appel de test. Les Logs de refus peuvent prendre un certain temps à apparaître. Ajoutez tous les domaines requis à la section Domaines autorisés et réessayez jusqu’à ce que l’outil en lecture seule réussisse. Pour en savoir plus sur ces enregistrements, consultez Événements d'accès réseau sortant.

Étape 1 : bloquer les Opérations d'écriture avec une politique intégrée​

Attachez la politique de service GitHub intégrée et activez Disallow writes . Cette action bloque les outils qui créent, modifient ou suppriment des données sur GitHub tout en autorisant les outils en lecture seule. La politique est gérée par la plateforme ; vous n'avez donc pas besoin d'écrire de fonction de politique.

  1. Dans la barre latérale du workspace, cliquez sur AI Gateway .
  2. Sur le tab MCPs , sélectionnez system.ai.github.
  3. Ouvrez l'tab Policies , puis cliquez sur New policy .
  4. Saisissez un nom de politique, tel que block_github_writes.
  5. Sous Guardrail type , sélectionnez GitHub .
  6. Sélectionnez Disallow writes , puis cliquez sur Create policy .

Une fois la politique associée, un tools/call pour un outil d'écriture est rejeté, y compris les outils qui créent des demandes d'extraction. Pour autoriser certains outils d'écriture tout en bloquant les opérations destructrices, créez plutôt une politique de service personnalisée. Pour en savoir plus sur les services disponibles et les contrôles de politiques, consultez Services MCP fournis par Databricks et Politiques de service.

Étape 2 : Partagez le service MCP avec votre équipe​

Les utilisateurs ont besoin de EXECUTE sur le service MCP, ainsi que de USE CATALOG et de USE SCHEMA sur system et system.ai. Pour accorder EXECUTE à votre équipe de développeurs depuis l'interface utilisateur :

  1. Dans l' AI Gateway , accédez au tab MCPs et sélectionnez le service MCP à partager, tel que system.ai.github.
  2. Allez à l'onglet Autorisations .
  3. Cliquez sur Accorder .
  4. Sélectionnez le principal autorisé à appeler le service MCP, tel que dev_team, sélectionnez le privilège EXECUTE , et cliquez sur Grant . Consultez la page Grant access to an MCP Service pour en savoir plus sur les autorisations de service.
remarque

Pour accorder l’accès à un service MCP dans system.ai, un administrateur de metastore doit d’abord s’accorder MANAGE sur le schéma system.ai.

Vérifiez les attributions existantes sur system.ai avant de considérer qu'il s'agit d'un accès réservé à l'équipe. Une attribution EXECUTE générale au niveau du schéma permet à d'autres utilisateurs d'invoquer le service même après que vous avez accordé l'accès dev_team. Pour remplacer l'attribution de schéma default par des stratégies pour les services MCP approuvés, consultez Gérer les modèles et les MCP avec des stratégies GRANT. Cette modification affecte également d'autres objets exécutables dans system.ai.

Étape 3 : Connecter votre agent de codage​

Installez un agent de codage compatible MCP si vous n'en possédez pas déjà un. Utilisez la CLI Unity Gateway (ug) pour configurer la connexion à la passerelle et lancer l'agent sur votre appareil. Par exemple, ug claude ouvre Claude Code avec cette configuration. Pour configurer vous-même un client, suivez la configuration manuelle ci-dessous.

  1. Si ug n'est pas installé, installez-le et vérifiez la version. Vous avez besoin de Python 3.12 ou version ultérieure et de uv. Consultez le guide de démarrage rapide de l'agent de codage pour obtenir des détails sur l'installation.

    Bash
    uv tool install git+https://github.com/databricks/unity-gateway
    ug --version

  2. Configurez votre agent de codage pour votre Workspace et connectez-vous lorsque vous y êtes invité. Si votre appareil est déjà configuré, passez cette étape.

    Bash
    ug configure --workspace https://<workspace-hostname>

  3. Ajoutez le service GitHub MCP à vos agents configurés. Si la configuration publiée par votre administrateur l'a déjà ajouté, passez cette étape.

    Bash
    ug mcp add --names system.ai.github

  4. Confirmez que le service apparaît dans vos connexions configurées :

    Bash
    ug mcp list

  5. Lancez ou redémarrez votre agent pour utiliser le service. Par exemple, lancez Claude Code :

    Bash
    ug claude

    Dans Claude Code, saisissez /mcp pour vérifier l'état de la connexion. Pour les autres commandes de lancement et options de configuration MCP, consultez Ajouter des outils et des compétences et la référence de la CLI ug.

Pour une configuration manuelle, suivez Connecter des serveurs MCP aux assistants d'IA et aux agents de codage pour Claude Code, Cursor et d'autres clients. Utilisez cet endpoint MCP pour le service intégré :

https://<workspace-url>/ai-gateway/mcp-services/system.ai.github

Pour des exemples d'appel, notamment le SDK OpenAI Agents, consultez Invoke the MCP Service.

Étape 4 : Confirmez que l'activité est régie et enregistrée.​

Vérifiez que la gouvernance fonctionne des deux côtés :

  • Application des règles : depuis l'agent, un outil en lecture seule s'exécute correctement, tandis qu'un outil d'écriture, tel qu'un outil créant une pull request, est rejeté avec une erreur de règle.

  • Journalisation de l'utilisation : Interrogez la table système d'utilisation pour confirmer que les appels sont enregistrés :

    SQL
    SELECT service_name, mcp_metadata.tool_name AS tool_name, status_code, COUNT(*) AS calls
    FROM system.ai_gateway.usage
    WHERE service_type = 'MCP_SERVICE'
      AND service_name = 'system.ai.github'
    GROUP BY service_name, mcp_metadata.tool_name, status_code
    ORDER BY calls DESC;

Pour en savoir plus sur le monitoring, consultez Surveiller l'utilisation et l'activité.

Étapes suivantes​

Sur cette page