Tutorial: Controlla l'accesso GitHub MCP di un agente di codifica

In questa esercitazione si regola l'accesso di un agente di scrittura del codice a GitHub usando Il catalogo unity e il gateway di intelligenza artificiale. Supponiamo che il tuo team utilizzi un agente di codifica come Claude Code o Cursor per leggere repository e pull request, ma tu voglia bloccare le operazioni di scrittura e auditare ogni chiamata di strumento.

Usi il system.ai.github servizio MCP che fornisce Azure Databricks, quindi non ospiti né registri un server MCP né crei una connessione a Unity Catalog. Colleghi una policy di servizio predefinita per bloccare le operazioni di scrittura, concedere al tuo team l'accesso, connettere un agente di sviluppo e verificare che ogni invocazione di uno strumento venga registrata.

Prerequisiti

Passo 1: Blocca le operazioni di scrittura con una policy integrata

Allega la policy di servizio integrata di GitHub e abilita Disallow writes. Questo blocca gli strumenti che creano, modificano o cancellano dati su GitHub, consentendo però strumenti di sola lettura. La policy è gestita dalla piattaforma, quindi non è necessario scrivere una funzione policy.

Interfaccia utente

  1. Nella barra laterale dell'area di lavoro fare clic su Gateway di intelligenza artificiale.
  2. Nella scheda MCPs, seleziona system.ai.github.
  3. Aprire la scheda Criteri , quindi fare clic su Nuovo criterio.
  4. Inserisci un nome di polizza, come block_github_writes.
  5. In Tipo di guardrail, seleziona GitHub.
  6. Seleziona Non consentire scritture, poi clicca Crea politica.

REST API

La policy API utilizza il system.ai.github_policy gestore con disallow_writes impostato a true:

databricks api patch \
  "/api/2.1/unity-catalog/mcp-services/system.ai.github?update_mask=config.service_policies" \
  --json '{
    "config": {
      "service_policies": [
        {
          "name": "block_github_writes",
          "policy_type": "POLICY_TYPE_BUILTIN",
          "handler": "system.ai.github_policy",
          "options": { "disallow_writes": "true" }
        }
      ]
    }
  }'

PATCH sostituisce l'elenco dei criteri del servizio. Se il servizio ha già delle politiche, includile service_policies in modo che restino collegate.

Con la policy allegata, una tools/call per uno strumento con accesso in scrittura viene rifiutata, compresi gli strumenti che creano pull request. Per consentire strumenti di scrittura selezionati bloccando operazioni distruttive, si crea invece una policy di servizio personalizzata . Per maggiori informazioni sui servizi disponibili e sui controlli delle policy, vedi Servizi MCP forniti da Databricks e politiche di servizio.

Passaggio 2: Condividere il servizio MCP con il team

Seleziona Condividi un MCP per dare al tuo team, ad dev_teamesempio, accesso a system.ai.github. Quella guida copre i permessi degli amministratori e l'accesso ereditato per gli MCP forniti da Databricks.

Passo 3: Collegare il tuo agente di programmazione

Installa un agente di codifica compatibile MCP se non ne hai già uno. Usa la CLI Gateway di Unity (ug) per configurare la connessione gateway e avviare l'agente sul tuo dispositivo. Ad esempio, ug claude apre Claude Code con tale configurazione. Per configurare un client da solo, segui la configurazione manuale qui sotto.

  1. Se ug non è installato, installalo e controlla la versione. Hai bisogno di Python 3.12 o versione successiva e di uv. Consulta la guida introduttiva rapida dell'agente di programmazione per i dettagli sull'installazione.

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

  2. Configura il tuo agente di programmazione per il tuo spazio di lavoro e accedi quando ti viene richiesto. Se il tuo dispositivo è già configurato, salta questo passaggio.

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

  3. Aggiungi il servizio GitHub MCP ai tuoi agenti configurati. Se la configurazione pubblicata dal tuo amministratore l'ha già aggiunta, salta questo passaggio.

    ug mcp add --names system.ai.github

  4. Conferma che il servizio appare nelle tue connessioni configurate:

    ug mcp list

  5. Avvia o riavvia il tuo agente per usare il servizio. Ad esempio, avvia Claude Code:

    ug claude

    In Claude Code, inserisci /mcp per controllare lo stato della connessione. Per altri comandi di avvio e opzioni di configurazione MCP, vedi Aggiungi strumenti e abilità e il riferimento alla CLI ug.

Per la configurazione manuale, scegli il tuo client in Supported coding agents. Usa questo endpoint MCP per il servizio integrato:

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

Per esempi di invocazione, incluso l'SDK OpenAI Agents, vedi Usa strumenti MCP in un agente Python.

Passaggio 4: Verificare che l'attività sia regolamentata e registrata

Verificate che la governance funzioni da entrambi i lati:

  • Applicazione delle policy: dall'agente, uno strumento di sola lettura ha successo, mentre uno strumento di scrittura, come quello che crea una pull request, viene rifiutato con un errore di policy.

  • Registrazione utilizzo: eseguire una query sulla tabella del sistema di utilizzo per verificare che le chiamate siano registrate:

    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;

Per altre informazioni sul monitoraggio, vedere Monitorare l'utilizzo.

Passaggi successivi

  • Ultimo aggiornamento: