Skip to main content
Last updated on

Govern an MCP service

Use Unity Catalog and Unity Gateway to control an MCP Service's tools, calls, access, and usage. You can govern both registered and Databricks-provided MCP Services. Tool selection applies only to registered services. Databricks-provided services have platform-managed tools.

The following table maps each governance goal to the control that addresses it. Select a goal for the steps.

Goal

Control

Limit which tools are exposed

Tool selection

Allow, block, or require approval for calls

Service policies

Control which providers a service can reach

Network policy

Control who can invoke a service

Unity Catalog privileges

Control which clients can connect

OAuth app and agent controls

Limit call volume

Rate limits

Monitor usage and activity

Usage, audit, and traces

Goal

Control

Limit which tools are exposed

Tool selection

Allow, block, or require approval for calls

Service policies

Control which providers a service can reach

Network policy

Control who can invoke a service

Unity Catalog privileges

Control which clients can connect

OAuth app and agent controls

Limit call volume

Rate limits

Monitor usage and activity

Usage, audit, and traces

Limit which tools are exposed​

By default, a registered MCP Service exposes all tools from its server. Select a subset during registration or update it later. A selector ending in * matches a prefix (get_*). Other selectors match an exact tool name (search_repositories).

To expose only read tools when you register an MCP Service:

  1. In AI Gateway > MCPs, start the MCP Service registration.
  2. Under Tools, select Advanced and enter get_* to include tools whose names start with get_. To select individual tools instead, choose Select manually.
  3. Leave Automatically include tools added to this server in the future off if new tools must be reviewed before they become available.

Unselected tools don't appear in tools/list. A tools/call for an unselected tool returns:

JSON
{ "code": -32003, "message": "Tool not allowed by MCP service configuration." }

Allow, block, or require approval for calls​

Beta

Service policies are in Beta. An account admin must enable the Unity Gateway beta features from the account console Previews page. See Manage Databricks previews.

A service 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 service to attach a policy. See Create and attach a service policy for the full setup requirements.

Example: Block PII in tool calls and results​

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

  1. In the workspace sidebar, click AI Gateway. On the MCPs tab, select the service.
  2. Open Policies > 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 service during Beta. For category behavior and more options, see Detect sensitive data with a service policy.

Example: Deny one tool to a specific agent​

For a registered MCP Service 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. In AI Gateway > MCPs, open the registered service and select Policies > 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.

Control which providers a service can reach​

The serverless network policy determines which providers an MCP Service can reach. This applies to registered external servers and Databricks-provided connected applications. With Restricted access, public destinations are blocked until you add their domains to Allowed domains.

For example, if a registered MCP server uses https://mcp.example.com/mcp, an account admin can allow it in the network policy for the workspace:

  1. In the account console, open Security > Networking > Context-based ingress & egress control.
  2. Open the policy associated with the workspace. If the workspace has no explicit assignment, open the default policy.
  3. On Egress, select Restricted access to specific destinations. Under Allowed domains, click Add destination and enter mcp.example.com.
  4. Click Update. Allow the change to propagate, then invoke a tool on the MCP Service. If another required host is blocked, check the outbound network logs and add that host too.

See Manage network policies for policy application details and Allow an MCP server in a network policy for MCP destinations.

A blocked call reports the destination, for example:

Text
Access to mcp.example.com is denied because of serverless network policy

A Unity Catalog connection does not automatically allow its destination in a restricted network policy. Implicit allowlisting for Unity Catalog connections is deprecated. For private destinations, see Reach an MCP server privately.

Control who can invoke a service​

Callers need EXECUTE on the MCP Service, plus USE CATALOG and USE SCHEMA on its parents. To share a registered service such as main.default.my_mcp with data-team:

  1. In AI Gateway > MCPs, open the service's Permissions tab.
  2. Click Grant, select data-team and EXECUTE, then click Grant.
  3. Confirm that the group can use the parent catalog and schema. See Grant access to an MCP Service for UI and API steps.

Review existing broad grants before restricting callers. Databricks-provided services can inherit a default EXECUTE grant on system.ai. For example, to grant access to approved services, apply a governed tag such as access_status = approved, then create a GRANT policy:

SQL
CREATE POLICY grant_approved_mcp_services
ON SCHEMA system.ai
COMMENT 'Grant EXECUTE on approved MCP services'
TO `account users`
GRANT EXECUTE FOR MCP SERVICES
WHEN has_tag_value('access_status', 'approved');

The policy grants access to tagged services. To keep untagged services inaccessible, remove any broad grant that also allows them. For the tagging steps and the impact of removing the default schema grant, follow Govern models and MCPs with GRANT policies. A Unity Catalog grant does not allow network egress.

Control which clients can connect​

When an external MCP client uses a dedicated Databricks OAuth application, an account admin can manage that application at Settings > App connections in the account console. For example, create an app connection for an approved coding agent, then configure the agent with its client ID. Removing the app connection disables that OAuth client account-wide. See Connect clients using OAuth, Enable or disable OAuth applications, and OAuth user authorization for background on tokens and consent.

For an agent acting on a user's behalf, a custom service policy can check its OAuth client ID to deny a specific tool or service call. The push_files example above shows the per-tool pattern. This check works only when the call carries the agent's client ID. Clients configured through the Unity Gateway CLI use a Databricks CLI login instead of a separate OAuth app. To restrict inbound client IPs for a workspace, see Workspace IP access lists.

Limit call volume​

Set rate limits to protect an external server and control call volume. For example, cap the service at 60 tool calls per minute across all callers:

  1. In AI Gateway > MCPs, open the service.
  2. On Overview, find Rate limits and click Set up (or Edit if limits already exist).
  3. Enter 60 in the Service QPM field, then click Save.

MCP rate limits apply to tools/call requests and use queries per minute (QPM), not tokens. A call that exceeds the limit returns HTTP 429. See Apply rate limits to model and MCP services for per-user and group limits.

Monitor usage and activity​

Unity Gateway records MCP Service activity in these system tables:

For example, count calls to each GitHub 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.

On this page