Tutorial: Controla o acesso ao GitHub MCP de um agente de programação

Neste tutorial, governa o acesso de um agente de programação ao GitHub usando o Unity Catalog e o AI Gateway. Suponha que a sua equipa usa um agente de programação como Claude Code ou Cursor para ler repositórios e pull requests, mas quer bloquear operações de escrita e auditar cada chamada de ferramenta.

Usas o system.ai.github serviço MCP que o Azure Databricks fornece, por isso não alojas nem registas um servidor MCP nem crias uma ligação ao Unity Catalog. Anexas uma política de serviço incorporada para blocar operações de escrita, concedes acesso à tua equipa, ligas um agente de programação e confirmas que todas as chamadas de ferramenta estão registadas.

Pré-requisitos

Passo 1: Bloquear operações de escrita com uma política integrada

Anexe a política de serviço integrada do GitHub e ative Impedir escritas. Isto bloqueia ferramentas que criam, modificam ou eliminam dados no GitHub, ao mesmo tempo que permite ferramentas só de leitura. A política é gerida pela plataforma, por isso não precisas de escrever uma função de política.

IU

  1. Na barra lateral do espaço de trabalho, clique em AI Gateway.
  2. No separador MCPs, selecione system.ai.github.
  3. Abra o separador Políticas e, em seguida, clique em Nova política.
  4. Insira um nome de apólice, como block_github_writes.
  5. Em Tipo Guardrail, selecione GitHub.
  6. Seleciona Despermitir escritas e depois clica em Criar política.

API REST

A política da API usa o system.ai.github_policy handler com disallow_writes definido para 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" }
        }
      ]
    }
  }'

Substitui PATCH a lista de políticas do serviço. Se o serviço já tiver políticas, inclua-as em service_policies para que permaneçam associadas.

Com a política anexada, uma tools/call ferramenta for a write é rejeitada, incluindo ferramentas que criam pull requests. Para permitir ferramentas de escrita selecionadas enquanto bloqueiam operações destrutivas, crie uma política de serviço personalizada . Para mais informações sobre os serviços disponíveis e os controlos de políticas, consulte Serviços MCP fornecidos pela Databricks e políticas de serviço.

Passo 2: Partilhe o Serviço MCP com a sua equipa

Selecione Partilhe um MCP para dar à sua equipa, como dev_team, acesso a system.ai.github. Este guia cobre permissões de administrador e acesso herdado para MCPs fornecidos pela Databricks.

Passo 3: Liga o teu agente de codificação

Instala um agente de codificação compatível com MCP se ainda não tiveres um. Utilize a CLI do Unity Gateway (ug) para configurar a ligação ao gateway e iniciar o agente no seu dispositivo. Por exemplo, ug claude abre o Claude Code com essa configuração. Para configurar um cliente manualmente, siga as instruções de configuração manual abaixo.

  1. Se ug não estiver instalado, instale-o e verifique a versão. Precisas de Python 3.12 ou posterior e uv. Consulte o guia de introdução rápida do agente de programação para obter detalhes sobre a instalação.

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

  2. Configura o teu agente de programação para o teu espaço de trabalho e inicia sessão quando for solicitado. Se o teu dispositivo já estiver configurado, salta este passo.

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

  3. Adicione o Serviço GitHub MCP aos seus agentes configurados. Se a configuração publicada pelo administrador já a adicionou, salta este passo.

    ug mcp add --names system.ai.github

  4. Confirme que o serviço aparece nas suas ligações configuradas:

    ug mcp list

  5. Inicie ou reinicie o seu agente para usar o serviço. Por exemplo, inicie o Claude Code:

    ug claude

    No Claude Code, introduza /mcp para verificar o estado da ligação. Para outros comandos de lançamento e opções de configuração do MCP, veja Adicionar ferramentas e competências e a referência à CLI da UG.

Para configuração manual, escolha o seu cliente em Assistentes de programação suportados. Use este endpoint MCP para o serviço incorporado:

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

Para exemplos de invocação, incluindo o SDK OpenAI Agents, veja Usar ferramentas MCP num agente Python.

Passo 4: Confirmar que a atividade está regida e registada

Verifique se a governação está a funcionar de ambos os lados:

  • Aplicação de políticas: A partir do agente, uma ferramenta de apenas leitura tem sucesso, enquanto uma ferramenta de escrita, como uma que cria um pull request, é rejeitada com um erro de política.

  • Registo de utilização: Consulte a tabela do sistema de utilização para confirmar que as chamadas foram registadas:

    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;

Para mais informações sobre monitorização, consulte Utilização do monitor.

Passos seguintes

  • Última atualização a