Create and attach a service policy

Beta

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

For an overview of service policies, see Service policies for AI securables.

To create a service policy, you write a SQL policy function, then attach it to an MCP Service or Model Service through the Unity AI Gateway UI. The policy governs each interaction at two evaluation points: ON CALL (before Databricks invokes the service) and ON RESULT (after the service responds).

Prerequisites

• An account administrator must enable the beta for your account from the Previews page in the account console.
• To create the policy function: CREATE FUNCTION privilege on the target schema.
• To attach a policy to a service: MANAGE on the target service securable and EXECUTE on the policy function.

Step 1: Write the policy function

A service policy function is a SQL UDF registered in Unity Catalog. It takes a single VARIANT parameter, event (the interaction data and context), and returns a VARIANT result:

SQL

CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
  event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;

The function runs at both evaluation points; branch on event:type::string ('request' for ON CALL, 'response' for ON RESULT) to act on a single phase. For the full event fields, the return value, and the supported SQL subset, see Service policy function reference.

Write a decision policy

A Decision Policy returns a VARIANT with a result field of ALLOW, DENY, or ASK and an optional reason. Build the result with named_struct and wrap it in to_variant_object so the function returns a VARIANT, keeping result and reason as top-level fields.

Example: deny a GitHub push from an MCP Service

This policy blocks any call to the push_files tool and allows all other interactions. Because the policy is attached to a specific MCP Service, the function only needs to check the tool name:

SQL

CREATE OR REPLACE FUNCTION main.governance.block_github_push(
  event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN
  CASE
    WHEN event:type::string = 'request'
      AND event:context.tool.name::string = 'push_files'
    THEN to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))
    ELSE to_variant_object(named_struct('result', 'ALLOW', 'reason', ''))
  END;

The result value determines what happens (it is case-insensitive):

• ALLOW: the interaction proceeds.
• DENY: Databricks blocks the interaction. The caller receives a structured error with the reason.
• ASK: the interaction pauses for human approval before proceeding.

For the supported SQL subset and the rules for returning a VARIANT, see Service policy function reference.

Step 2: Attach the policy to a service

During the Beta, you attach a service policy through the Unity AI Gateway UI, on an individual MCP Service or Model Service. You can attach more than one policy to a service: each attachment has a priority (rank), and the chain stops at the first DENY. At ON CALL, policies are evaluated in ascending rank order (lowest first); at ON RESULT, in the reverse order.

To attach a policy:

1. In the workspace sidebar, click AI Gateway.
2. Select the service to govern: a model service on the Models tab, or an MCP service on the MCPs tab.
3. Open the Policies tab, then click New policy.
4. Enter a Name for the policy.
5. Under Applied to, select which principals the policy applies to. The default, All account users, applies it to everyone.
6. In Guardrail type, select what the policy runs:
   • A built-in guardrail, such as PII Blocking or Unsafe Content. The Evaluator model service that runs the check (the LLM judge) is preselected; to use a different one, expand Advanced options and select it (you need CAN_QUERY on the model you choose).
   • Custom: click Custom function, then Select function, and select the SQL function you wrote in Step 1.
7. Under Phase, select where the policy runs: Input guardrails (ON CALL, before the service is invoked), Output guardrails (ON RESULT, after it responds), or both. A custom function can run in both phases and branch on event:type to scope itself to one. Some built-in guardrails run in only one phase, such as jailbreak detection on input and hallucination detection on output.
8. Set the Rank to control evaluation order. The lowest rank runs first on the request and last on the response.
9. Click Create policy.

The policy appears on the service's Policies tab. During the Beta, allow a short time for it to propagate before you test.

note

During the Beta, the policy UI might change. If a label differs from these steps, follow the in-product labels.

Use a built-in policy

Databricks provides built-in service policies in the system.ai catalog, such as system.ai.block_pii to block personally identifiable information. To use one, follow Step 2 but choose the built-in guardrail in Guardrail type instead of Custom. Built-in guardrails don't take any policy-specific configuration: you set the same Phase, Rank, Evaluator model service, and Mode fields as for any policy.

For the full list of built-in policies, see Built-in service policies.

You need the EXECUTE privilege on the built-in policy function and MANAGE on the target service.

Verify the policy

After you attach a policy, verify that it is active and producing the expected outcomes.

note

After you attach or change a policy, allow a short time for the change to take effect before you test. During the beta, policy changes can take up to a minute or two to propagate.

Confirm attachment

In the Unity AI Gateway, open the target service and view its attached policies. The policy you created appears in the list.

Observe policy outcomes

You can confirm a policy is taking effect:

• From the caller: when the policy returns DENY, the caller receives a structured error that includes the reason you specified. ASK pauses the call for human approval.
• In system tables: model and MCP activity is recorded in the usage tables, and full request and response payloads in inference tables.

Limitations

The following limitations apply during the beta:

• Transformation: Service policies return a decision (ALLOW, DENY, or ASK); they don't transform request or response content during the beta.
• Policy language: Custom policy functions support only LANGUAGE SQL.
• Attachment scope: Policy attachment is UI-only and scoped to an individual service, and the policy applies to all account users. Attaching policies at the catalog or schema level, attribute-based access control (ABAC) conditions, and custom principals are not available.