Skip to main content
Last updated on

Govern an MCP

Use Unity Catalog and Unity Gateway to share an MCP, choose its tools, and control usage. These controls apply to registered and Databricks-provided MCPs.

Share an MCP​

Callers need EXECUTE on the MCP, USE CATALOG and USE SCHEMA on its parents, and assignment to the workspace. Tools can also require access to underlying data or resources. To share main.default.my_mcp with data-team, use an identity that can manage its permissions:

  1. Open Unity Gateway, select MCPs, and open the MCP's Permissions tab.
  2. Click Grant, select data-team and EXECUTE, then click Grant.
  3. In Catalog Explorer, grant the group USE CATALOG on the parent catalog and USE SCHEMA on the parent schema.

End users don't need USE CONNECTION. Reserve it for MCP authors and administrators because it permits direct use of the connection outside the MCP's tool selection and policies. For automation, see Grant access programmatically.

To grant access to a Databricks-provided MCP, a metastore admin must first grant themselves MANAGE on the system.ai schema. These MCPs can inherit a default EXECUTE grant on system.ai. To restrict them, review those broad grants and follow Govern models and MCPs with GRANT policies.

Choose available tools​

Registered MCPs expose all server tools by default. During registration, under Tools:

  • Choose Select manually to select individual tools.
  • Choose Advanced to enter exact names or prefixes such as get_*.
  • Leave Automatically include tools added to this server in the future off if new tools must be reviewed first.

Exclusion patterns such as !delete_* aren't supported.

Unselected tools don't appear in tools/list, and calls to them return Tool not allowed by MCP service configuration.

To change tool selection later, update the MCP configuration with config.include_tool_selectors. An empty list exposes all tools.

Apply policies​

Beta

Service policies on MCPs are in Beta and require the Unity Ai Gateway Service Policies preview. A workspace admin turns it on from the Previews page. See Manage workspace-level previews.

A policy evaluates a tool call before it runs (ON CALL) and can evaluate its result (ON RESULT). It can allow, block, or require approval for a call without changing the tool list. You need MANAGE on the MCP to attach a policy. See Create and attach a policy for the full setup requirements.

Block sensitive data in tool calls and results​

Use the built-in Sensitive Data Detection policy to block calls containing personally identifiable information (PII):

  1. Open Unity Gateway, select MCPs, and open the MCP.
  2. Open Policies, click New policy, and enter a name, such as block_sensitive_data.
  3. Under Guardrail type, select Sensitive Data Detection.
  4. Under Classification tags, select the categories to block, such as class.us_ssn and class.credit_card. Select Block as the action.
  5. Under Phase, select both Input and Output to inspect tool arguments and tool results.
  6. Set the Rank, then click Create policy.

The policy applies to all account users on the MCP during Beta. For category behavior and more options, see Detect sensitive data with a policy.

Restrict a tool for a specific agent​

For a registered MCP that exposes push_files, this custom function denies that tool when the acting agent has a specific OAuth client ID. Replace <agent-oauth-client-id> with the agent's client ID and main.governance with a schema where you can create functions:

SQL
CREATE OR REPLACE FUNCTION main.governance.block_agent_push(event VARIANT)
RETURNS VARIANT
LANGUAGE SQL
RETURN
  CASE
    WHEN event:type::string = 'request'
      AND event:context.tool.name::string = 'push_files'
      AND event:context.actor.context.is_on_behalf_of::boolean = true
      AND event:context.actor.context.client_id::string = '<agent-oauth-client-id>'
    THEN to_variant_object(named_struct('result', 'DENY', 'reason', 'This agent cannot call push_files.'))
    ELSE to_variant_object(named_struct('result', 'ALLOW', 'reason', ''))
  END;
  1. Run the SQL in a SQL editor to create the function.
  2. Open the MCP's Policies tab and click New policy.
  3. Enter a name, select Custom under Guardrail type, then select the function. Set the Rank and click Create policy.
  4. Call push_files through that agent to verify the denial. A call through a different agent should remain allowed by this policy.

This example identifies the agent only for on-behalf-of calls that include its OAuth client ID. The tool still appears in tools/list. To remove it for every caller, use tool selection. See Policy function reference for the actor fields and custom policy setup for function privileges. For a built-in GitHub write policy, follow Govern a coding agent's GitHub MCP access.

Enforce a partner guardrail on tool calls​

If you already use a third-party guardrail vendor that implements the Databricks external policy API, attach an external service policy to the MCP. Databricks sends the vendor the tool name and arguments on the input phase and the tool result on the output phase, and enforces the vendor's ALLOW or DENY verdict.

  1. Open the MCP's Policies tab and click New policy.
  2. Enter a name, and select External under Guardrail type.
  3. Select an existing Unity Catalog HTTP connection to your vendor's endpoint, or create one with the vendor's OAuth machine-to-machine credentials.
  4. Under Phase, select Input, Output, or both. Set the Rank, then click Create policy.

External service policies fail closed: if the vendor's endpoint is unreachable or slow, Databricks denies the call. For connection fields, the content sent to the vendor, and network egress guidance, see Enforce a partner guardrail with an external service policy.

Limit call volume​

To cap an MCP at 60 tool calls per minute across all callers:

  1. Open the MCP in Unity Gateway, under MCPs.
  2. On Overview, find Rate limits and click Set up or Edit.
  3. Enter 60 in the Service QPM field and click Save.

MCP rate limits apply to tools/call requests and use queries per minute (QPM). Calls over the limit return HTTP 429. See Rate limits for per-user and group limits.

Monitor usage​

  • Usage: View call volume, errors, and latency in the usage dashboard, or query system.ai_gateway.usage with service_type = 'MCP_SERVICE'.
  • Audit: Review MCP changes and invocations (mcpCall) in system.access.audit. See Audit logs.
  • Traces: Inspect tool requests, responses, and policy decisions in the unified trace table after an admin enables it.

Example: count calls by tool​

SQL
SELECT mcp_metadata.tool_name AS tool_name, COUNT(*) AS calls
FROM system.ai_gateway.usage
WHERE service_type = 'MCP_SERVICE'
  AND service_name = 'system.ai.github'
GROUP BY mcp_metadata.tool_name
ORDER BY calls DESC;

For access to system tables, see Monitor account activity with system tables.

Network and client access​

Use network rules to control connectivity and OAuth client settings to manage client access.

External destinations​

For outbound network rules and private endpoints, follow Workspace to external MCP server and Private connectivity.

Client access​

An account admin can enable or disable a dedicated OAuth client from App connections in account settings. Disabling it affects that OAuth client account-wide. Clients configured through the Unity Gateway CLI use a Databricks CLI login instead of a dedicated OAuth app.

To restrict a specific agent's calls, use the policy example above. It requires on-behalf-of calls carrying the agent's OAuth client ID. For inbound IP restrictions, see Workspace IP access lists.

Update or delete an MCP​

You need ownership or MANAGE on the MCP, plus USE CATALOG and USE SCHEMA on its parents. Open the MCP from the MCPs page or Catalog Explorer:

  • Update: Edit its configuration and save. The MCP name cannot be changed.
  • Delete: Open the three-dot menu and select Delete. Clients using its URL can no longer call it.

For automation, see Update an MCP or Delete an MCP.

On this page