Tutorial: Govern a coding agent's GitHub MCP access

Important

This feature is in Beta. Account admins can manage access to this feature from the account console Previews page. See Manage Azure Databricks previews.

In this tutorial, you govern a coding agent's access to GitHub using Unity Catalog and AI Gateway. Suppose your team uses a coding agent such as Claude Code or Cursor with GitHub's MCP server, and you want developers to read repositories and open pull requests through the agent, but never to force-push or delete, with every tool call audited.

You use the pre-built system.ai.github MCP Service that Azure Databricks provides, so you don't host or register an MCP server or create a Unity Catalog connection. You attach a built-in service policy to block write operations, grant your team access, connect a coding agent, and confirm that every tool call is logged.

Prerequisites

  • A workspace enabled for Unity Catalog. See Get started with Unity Catalog.
  • The Unity AI Gateway preview and the Databricks-provided MCP Services preview enabled for your account. See Manage Azure Databricks previews.
  • The following privileges on the built-in service system.ai.github:
    • MANAGE, to attach a service policy.
    • EXECUTE, to invoke the service and to grant access to others.
  • The Azure Databricks CLI, authenticated to your workspace.

Step 1: Block destructive operations with a built-in policy

The system.ai.github MCP Service exposes GitHub's read tools and, by default, fails closed on write tools. To make that guarantee explicit and governed, attach the built-in system.ai.github_policy policy with the disallow_writes option. Built-in policies are platform-managed: you reference the handler instead of writing your own function.

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" }
        }
      ]
    }
  }'

With the policy attached, a tools/call for any write tool (a tool not marked read-only) is rejected, while read and pull-request tools continue to work. For more about built-in services and policies, see Databricks-provided MCP Services and Service policies for AI securables.

Step 2: Share the MCP Service with your team

By default, only principals with EXECUTE can invoke the service. To grant your developer team access from the UI:

  1. In the AI Gateway, go to the MCPs tab and select the MCP Service to share, such as system.ai.github.
  2. Go to the Permissions tab.
  3. Click Grant.
  4. Specify the principal to allow to invoke the MCP Service, such as dev_team, select the EXECUTE privilege, and click Confirm.

Note

To grant access on an MCP Service in system.ai, a metastore admin must first grant themselves MANAGE on the system.ai schema.

Step 3: Connect your coding agent

Point your coding agent at the AI Gateway MCP endpoint for the built-in service:

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

Each developer authenticates to Azure Databricks and must have EXECUTE on the MCP Service. For agent-specific setup steps for Claude Code, Cursor, and other tools, see Connect MCPs to AI assistants and coding agents. For invocation examples, including the OpenAI Agents SDK, see Invoke the MCP Service.

Step 4: Confirm activity is governed and logged

Verify that governance is working from both ends:

  • Policy enforcement: From the agent, a read or pull-request tool succeeds, while a write tool is rejected with a policy error.

  • Usage logging: Query the usage system table to confirm calls are recorded:

    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;

For more about monitoring, see Monitor usage.

Next steps

  • Last updated on