w.ai_gateway: AI Gateway

class databricks.sdk.service.catalog.AiGatewayAPI

Govern AI workloads in Unity Catalog. This API manages the Unity Catalog securables that bring centralized access control, lineage, and auditing to AI-serving entities: model services (governed access to foundation models and external LLMs), model provider services (governed resources for external model providers), and MCP services (governed Model Context Protocol servers).

create_mcp_service(mcp_service: McpService, parent: str, mcp_service_id: str) → McpService

Creates an MCP service in a Unity Catalog schema. An MCP (Model Context Protocol) service is a governed securable that registers an MCP server and exposes its tools for discovery, access control, and invocation. Specify its name in mcp_service_id.

You must be the owner of the parent schema or have the CREATE_SERVICE and USE_SCHEMA privileges on the parent schema and USE_CATALOG on the parent catalog. You also need USE_CONNECTION on the connection the MCP service references.

Parameters:

• mcp_service – McpService The MCP service to create. Do not set name; the server derives it from parent and mcp_service_id. source_connection is required.

• parent – str Name of the parent schema. Format: schemas/{catalog}.{schema}. Each {...} component is capped at 255 characters individually.

• mcp_service_id – str Name for the MCP service, e.g. “my_mcp_service”.

Returns:

McpService

create_mcp_service_user_mapped_credential(name: str, login: McpServiceUserMappedCredentialLogin) → McpServiceUserMappedCredential

Logs the caller in to an MCP service: creates their per-user OAuth credential, or re-authenticates it if one already exists. The request body carries the OAuth exchange fields.

You must be the owner of the MCP service or have EXECUTE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

• name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}.

• login – McpServiceUserMappedCredentialLogin

Returns:

McpServiceUserMappedCredential

create_model_provider_service(model_provider_service: ModelProviderService, parent: str, model_provider_service_id: str) → ModelProviderService

Creates a model provider service in a Unity Catalog schema. A model provider service stores authentication and request configuration for an external model provider, such as OpenAI, Azure OpenAI, or Amazon Bedrock. Model services reference it to invoke the provider. Specify its name in model_provider_service_id.

You must be the owner of the parent schema or have the CREATE_SERVICE and USE_SCHEMA privileges on the parent schema and USE_CATALOG on the parent catalog. Inline credentials additionally require CREATE_CONNECTION on the parent schema. When using a Unity Catalog service credential, you must have ACCESS on that credential.

Parameters:

• model_provider_service – ModelProviderService The model provider service to create. Do not set name; the server derives it from parent and model_provider_service_id.

• parent – str Name of the parent schema. Format: schemas/{catalog}.{schema}. Each {...} component is capped at 255 characters individually.

• model_provider_service_id – str Name for the model provider service, e.g. “openai_prod”.

Returns:

ModelProviderService

create_model_service(model_service: ModelService, parent: str, model_service_id: str) → ModelService

Creates a model service in a Unity Catalog schema. A model service is a governed AI Gateway endpoint that routes inference requests to one or more model destinations. Specify its name in model_service_id.

You must be the owner of the parent schema or have the CREATE_SERVICE and USE_SCHEMA privileges on the parent schema and USE_CATALOG on the parent catalog. For every destination, you also need USE_CATALOG and USE_SCHEMA on its parent and EXECUTE on the referenced Unity Catalog model or model provider service. A provisioned-throughput destination additionally requires CAN_MANAGE on its Model Serving endpoint. Configuring an inference table additionally requires CREATE_TABLE.

Parameters:

• model_service – ModelService The model service to create. Do not set name; the server derives it from parent and model_service_id.

• parent – str Name of the parent schema. Format: schemas/{catalog}.{schema}. Each {...} component is capped at 255 characters individually.

• model_service_id – str Name for the model service, e.g. “my_model_service”.

Returns:

ModelService

delete_mcp_service(name: str [, etag: Optional[str]])

Deletes the MCP service identified by its resource name. Optionally supply an etag to make the delete conditional on the MCP service not having changed since it was read.

You must be the owner of the MCP service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

• name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}. Each {...} component is capped at 255 characters individually.

• etag – str (optional) Optimistic concurrency token from the most recent read. When set, the delete succeeds only if the resource has not changed. Leave unset for an unconditional delete. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

delete_mcp_service_user_mapped_credential(name: str) → DeleteMcpServiceUserMappedCredentialResponse

Revokes (deletes) the caller’s per-user OAuth credential for an MCP service (logout).

You must be the owner of the MCP service or have EXECUTE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}.

Returns:

DeleteMcpServiceUserMappedCredentialResponse

delete_model_provider_service(name: str [, etag: Optional[str]])

Deletes the model provider service identified by its resource name. Optionally supply an etag to make the delete conditional on the model provider service not having changed since it was read.

You must be the owner of the model provider service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

• name – str Resource name of the model provider service. Format: model-provider-services/{catalog}.{schema}.{model_provider_service}. Each {...} component is capped at 255 characters individually.

• etag – str (optional) Optimistic concurrency token from the most recent read. When set, the delete succeeds only if the resource has not changed. Leave unset for an unconditional delete. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

delete_model_service(name: str [, etag: Optional[str]])

Deletes the model service identified by its resource name. Optionally supply an etag to make the delete conditional on the model service not having changed since it was read.

You must be the owner of the model service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

• name – str Resource name of the model service. Format: model-services/{catalog}.{schema}.{model_service}. Each {...} component is capped at 255 characters individually.

• etag – str (optional) Optimistic concurrency token from the most recent read. When set, the delete succeeds only if the resource has not changed. Leave unset for an unconditional delete. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

get_mcp_service(name: str) → McpService

Returns the MCP service identified by its resource name.

You must be the owner of the MCP service or have EXECUTE, READ_METADATA, or MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}. Each {...} component is capped at 255 characters individually.

Returns:

McpService

get_mcp_service_user_mapped_credential(name: str) → McpServiceUserMappedCredential

Returns the caller’s per-user OAuth login state for an MCP service. Read provisioning_info.state: ACTIVE means the caller is logged in and the credential is usable; any other state (for example a failed or still-provisioning login) means the login has not completed and the caller should log in again. If the caller has no credential yet, the RPC returns NOT_FOUND.

You must be the owner of the MCP service or have EXECUTE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}.

Returns:

McpServiceUserMappedCredential

get_model_provider_service(name: str) → ModelProviderService

Returns the model provider service identified by its resource name.

You must be the owner of the model provider service or have EXECUTE, READ_METADATA, or MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

name – str Resource name of the model provider service. Format: model-provider-services/{catalog}.{schema}.{model_provider_service}. Each {...} component is capped at 255 characters individually.

Returns:

ModelProviderService

get_model_service(name: str) → ModelService

Returns the model service identified by its resource name.

You must be the owner of the model service or have EXECUTE, READ_METADATA, or MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

name – str Resource name of the model service. Format: model-services/{catalog}.{schema}.{model_service}. Each {...} component is capped at 255 characters individually.

Returns:

ModelService

list_mcp_services([, page_size: Optional[int], page_token: Optional[str], parent: Optional[str], view: Optional[ListMcpServicesRequestView]]) → Iterator[McpService]

Lists the MCP services in a Unity Catalog schema. Provide parent as schemas/{catalog}.{schema}. Results are paginated; pass the returned next_page_token to fetch subsequent pages.

Requires USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema. Only MCP services the caller can access (as owner or through EXECUTE, READ_METADATA, or MANAGE) are returned.

Parameters:

• page_size – int (optional) Maximum number of MCP services to return. Defaults to 100 when unset or 0; the maximum is 100. Use page_token to retrieve additional pages.

• page_token – str (optional) Opaque pagination token from the previous response.

• parent – str (optional) Parent schema to list within, in the form schemas/{catalog}.{schema}. Required. Each {...} component is capped at 255 characters individually.

• view – ListMcpServicesRequestView (optional) Fields to return for each service. FULL includes source-connection details and rate-limit principal names. BASIC omits the source connection and omits principal names from rate limits. Defaults to BASIC when unset.

Returns:

Iterator over McpService

list_model_provider_services([, page_size: Optional[int], page_token: Optional[str], parent: Optional[str], view: Optional[ListModelProviderServicesRequestView]]) → Iterator[ModelProviderService]

Lists the model provider services in a Unity Catalog schema. Provide parent as schemas/{catalog}.{schema}. Results are paginated; pass the returned next_page_token to fetch subsequent pages.

Requires USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema. Only model provider services the caller can access (as owner or through EXECUTE, READ_METADATA, or MANAGE) are returned.

Parameters:

• page_size – int (optional) Maximum number of provider services to return. Defaults to 100 when unset or 0; the maximum is 100. Use page_token to retrieve additional pages.

• page_token – str (optional) Opaque pagination token from the previous response.

• parent – str (optional) Parent schema to list within, in the form schemas/{catalog}.{schema}. Required. Each {...} component is capped at 255 characters individually.

• view – ListModelProviderServicesRequestView (optional) Fields to return for each service. FULL includes resolved service-credential and inference-table details and rate-limit principal names. BASIC omits those details and principal names from rate limits. Defaults to BASIC when unset.

Returns:

Iterator over ModelProviderService

list_model_services([, page_size: Optional[int], page_token: Optional[str], parent: Optional[str], view: Optional[ListModelServicesRequestView]]) → Iterator[ModelService]

Lists the model services in a Unity Catalog schema. Provide parent as schemas/{catalog}.{schema}. Results are paginated; pass the returned next_page_token to fetch subsequent pages.

Requires USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema. Only model services the caller can access (as owner or through EXECUTE, READ_METADATA, or MANAGE) are returned.

Parameters:

• page_size – int (optional) Maximum number of model services to return. Defaults to 100 when unset or 0; the maximum is 100. Use page_token to retrieve additional pages.

• page_token – str (optional) Opaque pagination token from the previous response.

• parent – str (optional) Parent schema to list within, in the form schemas/{catalog}.{schema}. Required. Each {...} component is capped at 255 characters individually.

• view – ListModelServicesRequestView (optional) Fields to return for each service. FULL includes destinations, inference-table details, and rate-limit principal names. BASIC omits destinations and inference-table details and omits principal names from rate limits. Defaults to BASIC when unset.

Returns:

Iterator over ModelService

update_mcp_service(name: str, mcp_service: McpService, update_mask: FieldMask [, etag: Optional[str]]) → McpService

Updates an MCP service. Only the fields named in update_mask are changed; the resource name is immutable. Optionally supply an etag to make the update conditional on the MCP service not having changed since it was read.

You must be the owner of the MCP service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema. When changing config.source_connection.name, the MCP service owner must also have USE_CONNECTION on the new connection.

Parameters:

• name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + mcp_service_id; required and immutable on Update/Get/Delete.

• mcp_service – McpService The MCP service with the updated field values. name identifies the resource (mcp-services/{catalog}.{schema}.{mcp_service}); only fields listed in update_mask are applied.

• update_mask – FieldMask Fields to update. Use config to replace the entire configuration. The replacement must include every required field; any optional field you omit is cleared. To preserve sibling fields, use one or more granular paths: comment, config.source_connection.name, config.include_tool_selectors, or config.rate_limits.

• etag – str (optional) Optimistic concurrency token from the most recent read. When set, the update succeeds only if the resource has not changed. Leave unset for an unconditional update. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

Returns:

McpService

update_model_provider_service(name: str, model_provider_service: ModelProviderService, update_mask: FieldMask [, etag: Optional[str]]) → ModelProviderService

Updates a model provider service. Only the fields named in update_mask are changed; the resource name and provider type are immutable. Optionally supply an etag to make the update conditional on the model provider service not having changed since it was read.

You must be the owner of the model provider service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Updating config.provider cannot change the provider type or switch between Unity Catalog service-credential authentication and inline authentication.

Parameters:

• name – str Resource name of the provider service. Format: model-provider-services/{catalog}.{schema}.{model_provider_service}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + model_provider_service_id; required and immutable on Update/Get/Delete.

• model_provider_service – ModelProviderService The model provider service with the updated field values. name identifies the resource (model-provider-services/{catalog}.{schema}.{model_provider_service}); only fields listed in update_mask are applied.

• update_mask – FieldMask Fields to update. Use config to replace the entire configuration. The replacement must include every required field; any optional field you omit is cleared. To preserve sibling fields, use one or more granular paths: comment; config.provider to replace the active provider-specific value (for example, config.openai; the mask path remains config.provider); config.allow_all_targets, config.targets, config.forward_headers, config.forward_query_parameters, config.forward_unmanaged_paths, config.rate_limits, or config.inference_table. The provider type is immutable.

• etag – str (optional) Optimistic concurrency token from the most recent read. When set, the update succeeds only if the resource has not changed. Leave unset for an unconditional update. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

Returns:

ModelProviderService

update_model_service(name: str, model_service: ModelService, update_mask: FieldMask [, etag: Optional[str]]) → ModelService

Updates a model service. Only the fields named in update_mask are changed; the resource name is immutable. Optionally supply an etag to make the update conditional on the model service not having changed since it was read.

You must be the owner of the model service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema. When changing destinations, both you and the model service owner need USE_CATALOG and USE_SCHEMA on each destination’s parent and EXECUTE on the referenced Unity Catalog model or model provider service. A provisioned-throughput destination additionally requires CAN_MANAGE for you and CAN_QUERY for the model service owner. Adding an inference table additionally requires CREATE_TABLE.

Parameters:

• name – str Resource name of the model service. Format: model-services/{catalog}.{schema}.{model_service}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + model_service_id; required and immutable on Update/Get/Delete.

• model_service – ModelService The model service with the updated field values. name identifies the resource (model-services/{catalog}.{schema}.{model_service}); only fields listed in update_mask are applied.

• update_mask – FieldMask Fields to update. Use config to replace the entire configuration. The replacement must include every required field; any optional field you omit is cleared. To preserve sibling fields, use one or more granular paths: comment, config.routing.destinations, config.routing.fallback.destinations, config.rate_limits, or config.inference_table. Intermediate paths such as config.routing and config.routing.fallback are not supported.

• etag – str (optional) Optimistic concurrency token from the most recent read. When set, the update succeeds only if the resource has not changed. Leave unset for an unconditional update. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

Returns:

ModelService