Tutorial: Controla el acceso a GitHub MCP de un agente de programación

En este tutorial, controlará el acceso de un agente de codificación a GitHub mediante unity Catalog y AI Gateway. Supongamos que tu equipo usa un agente de codificación como Claude Code o Cursor para leer repositorios y pull requests, pero quieres bloquear operaciones de escritura y auditar cada llamada a herramienta.

Usas el system.ai.github servicio MCP que ofrece Azure Databricks, así que no alojas ni registras un servidor MCP ni creas una conexión con Unity Catalog. Adjunte una directiva de servicio integrada para bloquear las operaciones de escritura, conceder acceso al equipo, conectar un agente de codificación y confirmar que se registra cada llamada de herramienta.

Prerequisites

Paso 1: Bloquear las operaciones de escritura con una directiva integrada

Aplica la directiva de servicio integrada de GitHub y habilita No permitir escrituras. Esto bloquea las herramientas que crean, modifican o eliminan datos en GitHub, al tiempo que permite las herramientas de solo lectura. La directiva se administra desde la plataforma, por lo que no es necesario escribir una función de directiva.

Interfaz de usuario

  1. En la barra lateral del área de trabajo, haga clic en AI Gateway.
  2. En la pestaña MCP, selecciona system.ai.github.
  3. Abra la pestaña Directivas y haga clic en Nueva directiva.
  4. Introduce un nombre para la directiva, como block_github_writes.
  5. En Tipo de Guardrail, selecciona GitHub.
  6. Selecciona No permitir escrituras y, a continuación, haz clic en Crear directiva.

REST API

La directiva de API utiliza el controlador system.ai.github_policy con disallow_writes establecido en 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" }
        }
      ]
    }
  }'

El PATCH sustituye a la lista de directivas del servicio. Si el servicio ya tiene directivas, inclúyelas en service_policies para que sigan asociadas.

Con la directiva asociada, se rechaza cualquier tools/call para una herramienta de escritura, incluidas las herramientas que crean solicitudes de extracción. Para permitir determinadas herramientas de escritura y bloquear al mismo tiempo las operaciones destructivas, crea en su lugar una directiva de servicio personalizada. Para obtener más información sobre los servicios disponibles y los controles de directiva, consulta Servicios MCP proporcionados por Databricks y Políticas de servicio.

Paso 2: Compartir el servicio MCP con el equipo

Siga Compartir un MCP para dar acceso a system.ai.github a su equipo, por ejemplo a dev_team. Esa guía cubre los permisos de administrador y el acceso heredado para los MCPs proporcionados por Databricks.

Paso 3: Conecta tu agente de programación

Instala un agente de codificación compatible con MCP si aún no tienes uno. Utiliza la CLI de Unity Gateway (ug) para configurar la conexión a la pasarela e iniciar el agente en tu dispositivo. Por ejemplo, ug claude abre Claude Code con esa configuración. Para configurar un cliente por tu cuenta, sigue las instrucciones de configuración manual que se indican a continuación.

  1. Si ug no está instalado, instálalo y comprueba la versión. Necesitas Python 3.12 o posterior y uv. Consulta la guía de inicio rápido del agente de programación para obtener detalles sobre la instalación.

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

  2. Configura tu agente de programación para tu espacio de trabajo e inicia sesión cuando se te solicite. Si tu dispositivo ya está configurado, salta este paso.

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

  3. Añade el servicio GitHub MCP a tus agentes configurados. Si la configuración publicada por tu administrador ya lo añadió, sáltate este paso.

    ug mcp add --names system.ai.github

  4. Confirma que el servicio aparece en tus conexiones configuradas:

    ug mcp list

  5. Inicia o reinicia tu agente para utilizar el servicio. Por ejemplo, inicia Claude Code:

    ug claude

    En Claude Code, introduce /mcp para comprobar el estado de la conexión. Para otros comandos de lanzamiento y opciones de configuración de MCP, consulta Añadir herramientas y habilidades y la referencia de la CLI de ug.

Para la configuración manual, elija su cliente en Agentes de codificación admitidos. Utiliza este punto final MCP para el servicio integrado:

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

Para ejemplos de invocaciones, incluyendo el SDK de Agentes OpenAI, véase Usar herramientas MCP en un agente Python.

Paso 4: Confirmar que la actividad está sujeta a control y se registra

Compruebe que la gobernanza funciona desde ambos extremos:

  • Aplicación de directivas: desde el agente, una herramienta de solo lectura se ejecuta correctamente, mientras que una herramienta de escritura, como la que crea una solicitud de extracción, se rechaza con un error de directiva.

  • Registro de uso: consulte la tabla del sistema de uso para confirmar que las llamadas se registran:

    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 más información sobre la supervisión, consulte Supervisión del uso.

Pasos siguientes

  • Última actualización el