Tutorial: Control a coding agent's GitHub MCP access

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 to read repositories and pull requests, but you want to block write operations and audit every tool call.

You use the 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

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

Attach the built-in GitHub service policy and enable Disallow writes. This blocks tools that create, modify, or delete data on GitHub while allowing read-only tools. The policy is platform-managed, so you don't need to write a policy function.

UI

  1. In the workspace sidebar, click AI Gateway.
  2. On the MCPs tab, select system.ai.github.
  3. Open the Policies tab, then click New policy.
  4. Enter a policy name, such as block_github_writes.
  5. Under Guardrail type, select GitHub.
  6. Select Disallow writes, then click Create policy.

REST API

The API policy uses the system.ai.github_policy handler with disallow_writes set to 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" }
        }
      ]
    }
  }'

The PATCH replaces the service's policy list. If the service already has policies, include them in service_policies so they remain attached.

With the policy attached, a tools/call for a write tool is rejected, including tools that create pull requests. To allow selected write tools while blocking destructive operations, create a custom service policy instead. For more about the available services and policy controls, see Databricks-provided MCP Services and Service policies.

Step 2: Share the MCP Service with your team

Follow Share an MCP to give your team, such as dev_team, access to system.ai.github. That guide covers administrator permissions and inherited access for Databricks-provided MCPs.

Step 3: Connect your coding agent

Install an MCP-capable coding agent if you don't already have one. Use the Unity Gateway CLI (ug) to configure the gateway connection and launch the agent on your device. For example, ug claude opens Claude Code with that configuration. To configure a client yourself, follow the manual setup below.

  1. If ug isn't installed, install it and check the version. You need Python 3.12 or later and uv. See the coding agent quickstart for installation details.

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

  2. Configure your coding agent for your workspace and sign in when prompted. If your device is already configured, skip this step.

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

  3. Add the GitHub MCP Service to your configured agents. If your admin's published configuration already added it, skip this step.

    ug mcp add --names system.ai.github

  4. Confirm that the service appears in your configured connections:

    ug mcp list

  5. Launch or restart your agent to use the service. For example, launch Claude Code:

    ug claude

    In Claude Code, enter /mcp to check the connection status. For other launch commands and MCP setup options, see Add tools and skills and the ug CLI reference.

For manual setup, choose your client in Supported coding agents. Use this MCP endpoint for the built-in service:

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

For invocation examples, including the OpenAI Agents SDK, see Use MCP tools in a Python agent.

Step 4: Confirm activity is governed and logged

Verify that governance is working from both ends:

  • Policy enforcement: From the agent, a read-only tool succeeds, while a write tool, such as one that creates a pull request, 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