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

Neste tutorial, você controla o acesso de um agente de codificação a GitHub usando o Catálogo do Unity e o Gateway de IA. Suponha que sua equipe use um agente de programação como Claude Code ou Cursor para ler repositórios e pull requests, mas você queira bloquear operações de escrita e auditar cada chamada de ferramenta.

Você usa o system.ai.github serviço MCP que o Azure Databricks oferece, então não hospeda ou registra um servidor MCP nem cria uma conexão com o Unity Catalog. Você anexa uma política de serviço interna para bloquear operações de gravação, conceder acesso à sua equipe, conectar um agente de codificação e confirmar se cada chamada de ferramenta está registrada.

Pré-requisitos

Etapa 1: Bloquear operações de gravação com uma política interna

Anexe a política de serviço do GitHub embutida e ative o Disallow writes. Isso bloqueia ferramentas que criam, modificam ou excluem dados no GitHub, permitindo ferramentas somente leitura. A política é gerenciada pela plataforma, então você não precisa escrever uma função de política.

interface do usuário

  1. Na barra lateral do espaço de trabalho, clique em AI Gateway.
  2. Na guia MCPs, selecione system.ai.github.
  3. Abra a guia Políticas e clique em Nova política.
  4. Insira um nome de política, como block_github_writes.
  5. Em Tipo de barreira de proteção, selecione GitHub.
  6. Selecione Não permitir gravações, então clique 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" }
        }
      ]
    }
  }'

O PATCH substitui 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 anexadas.

Com a política anexada, uma tools/call para uma ferramenta de gravação é rejeitada, incluindo ferramentas que criam pull requests. Para permitir ferramentas de gravação 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 controles de políticas, consulte Serviços MCP fornecidos pelo Databricks e Políticas de serviço.

Etapa 2: Compartilhar o Serviço MCP com sua equipe

Siga Compartilhar um MCP para dar à sua equipe, como dev_team, acesso a system.ai.github. Esse guia cobre permissões de administrador e acesso herdado para MCPs fornecidos pelo Databricks.

Etapa 3: Conectar seu agente de codificação

Instale um Agente de codificação compatível com MCP, caso ainda não tenha um. Use a CLI do Gateway do Unity (ug) para configurar a conexão do gateway e iniciar o agente no seu dispositivo. Por exemplo, ug claude abre o Claude Code com essa configuração. Para configurar um cliente por conta própria, siga a configuração manual abaixo.

  1. Se ug não estiver instalado, instale-o e verifique a versão. Você precisa do Python 3.12 ou posterior e uv. Consulte o guia de início rápido do agente de código para obter detalhes sobre a instalação.

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

  2. Configure seu agente de codificação para seu workspace e entre quando solicitado. Se o seu dispositivo já estiver configurado, ignore esta etapa.

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

  3. Adicione o Serviço GitHub MCP aos seus agentes configurados. Se a configuração publicada pelo seu administrador já tiver adicionado isso, ignore esta etapa.

    ug mcp add --names system.ai.github

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

    ug mcp list

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

    ug claude

    No Claude Code, insira /mcp para verificar o status da conexão. Para outros comandos de lançamento e opções de configuração do MCP, veja Adicionar ferramentas e habilidades e a referência de CLI do ug.

Para configuração manual, escolha seu cliente em Agentes de código compatíveis. Use este endpoint MCP para o serviço embutido:

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

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

Etapa 4: Confirmar se a atividade é governada e registrada em log

Verifique se a governança está funcionando dos dois lados:

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

  • Registro de uso: consulte a tabela de sistema de uso para confirmar se as chamadas são registradas:

    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 obter mais informações sobre o monitoramento, consulte o uso do Monitor.

Próximas Etapas 

  • Última atualização em