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

  • A workspace enabled for Unity Catalog. See Get started with Unity Catalog.

  • The Unity Gateway beta features enabled for your account. An account admin can enable them from the account console Previews page. 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.

  • To use the REST API in Step 1, authenticate the Azure Databricks CLI to your workspace.

  • If your workspace uses a restricted serverless network policy, an account admin must allow the destinations required by the GitHub MCP Service.

    Find the required domains

    To find the required domains, connect your agent in Step 3 and try a read-only GitHub tool. If the network policy blocks the call, the error names the denied domain (Access to <fqdn> is denied because of serverless network policy). An account admin can add that domain to Allowed domains in the network policy and retry.

    If the call still fails, check the outbound network denial logs after another test call. Replace <workspace-id> with your workspace ID. The system.access schema must be enabled to query the table.

    SELECT event_time, destination
FROM system.access.outbound_network
WHERE workspace_id = '<workspace-id>'
  AND destination_type = 'DNS'
  AND access_type = 'DROP'
  AND event_time >= current_timestamp() - INTERVAL 15 MINUTES
ORDER BY event_time DESC;

    The table doesn't identify the MCP Service, so compare event_time with the test call. Denial logs can take time to appear. Add any required domains to Allowed domains and retry until the read-only tool succeeds. See Outbound network access events for more about these records.

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

Users need EXECUTE on the MCP Service, plus USE CATALOG and USE SCHEMA on system and system.ai. To grant your developer team EXECUTE 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. Select the principal to allow to invoke the MCP Service, such as dev_team, select the EXECUTE privilege, and click Grant. See Grant access to an MCP Service for more about service permissions.

Note

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

Check for existing grants on system.ai before treating this as team-only access. A broad schema-level EXECUTE grant can let other users invoke the service even after you grant dev_team access. To replace the default schema grant with policies for approved MCP Services, see Govern models and MCPs with GRANT policies. That change affects other executable objects in system.ai as well.

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, follow Connect MCPs to AI assistants and coding agents for Claude Code, Cursor, and other clients. 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 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-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 and activity.

Next steps

  • Last updated on