Mcp Service

View as Markdown

A governed MCP server registration in Unity Catalog. Acts as a container securable that references an MCP server -- customer-external via a UC Connection, or <Databricks>-hosted via an internal server -- and exposes its tools for discovery, authorization, and invocation.

GetGET /api/2.1/unity-catalog/{name=mcp-services/*}ListGET /api/2.1/unity-catalog/mcp-servicesCreatePOST /api/2.1/unity-catalog/mcp-servicesUpdatePATCH /api/2.1/unity-catalog/{mcp_service.name=mcp-services/*}DeleteDELETE /api/2.1/unity-catalog/{name=mcp-services/*}

McpService object

A governed MCP server registration in Unity Catalog. Acts as a container securable that references an MCP server -- customer-external via a UC Connection, or <Databricks>-hosted via an internal server -- and exposes its tools for discovery, authorization, and invocation.

namestring

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.

ownerstring

The owner of the MCP service. Write-only; read owner via effective_owner.

effective_ownerstring

The resolved owner of the MCP service. Falls back to the caller's identity when owner is not explicitly set on creation.

metastore_idstring

Metastore hosting the MCP service.

create_timestring

When the MCP service was created.

created_bystring

Creator identity.

update_timestring

When the MCP service was last modified.

updated_bystring

Identity of the last updater.

commentstring

User-provided description.

Constraints: <= 65536 characters

configobject

Operational configuration: connection, tool selectors, rate limit. Required on CreateMcpService; on UpdateMcpService it is required only when config (or a config.* subpath) appears in update_mask.

Show child attributesHide child attributes

source_connectionobject

UC Connection referencing the MCP server.

Show child attributesHide child attributes

namestring

Name of the UC connection that hosts the MCP server, as connections/{catalog}.{schema}.{connection}.

is_deletedboolean

include_tool_selectorsarray of string

Glob or exact-match patterns selecting which tools from the MCP server to expose. Prefix match for patterns with *, exact match otherwise. An empty list means all tools are included. Per-element max 256 chars.

rate_limitsarray of object

Per-principal rate limits applied to tool invocations routed through this MCP service. Repeated to support per-USER / USER_GROUP / SERVICE_PRINCIPAL / SERVICE / USER_DEFAULT scopes simultaneously, mirroring the ModelServiceConfig.rate_limits shape. Empty when no rate limit is configured.

Show child attributesHide child attributes

keystring

Scope key. Determines whether principal is required.

Values: RATE_LIMIT_KEY_USER, RATE_LIMIT_KEY_USER_GROUP, RATE_LIMIT_KEY_SERVICE_PRINCIPAL, RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, RATE_LIMIT_KEY_REQUEST_TAG

renewal_periodstring

Renewal period.

Values: RATE_LIMIT_RENEWAL_PERIOD_MINUTE, RATE_LIMIT_RENEWAL_PERIOD_HOUR

principalstring

Principal this limit applies to: user email, group name, or service principal application ID. Required unless key is RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, or RATE_LIMIT_KEY_REQUEST_TAG (which must not set a principal).

requestsint64

Max requests allowed within a renewal period. Leave unset for no request limit.

tokensint64

Max tokens allowed within a renewal period. Leave unset for no token limit.

request_tag_keystring

Request tag key this limit applies to. Required when key is RATE_LIMIT_KEY_REQUEST_TAG, forbidden otherwise.

request_tag_valuestring

Request tag value this limit applies to. Only valid when key is RATE_LIMIT_KEY_REQUEST_TAG. Leave unset to apply the limit to every value of request_tag_key (an any-value default); a set value is a specific override for that value.

etagstring

Optimistic concurrency control token. Server-generated from the entity's state and returned on every read. To use it as an if-match precondition on a mutation, echo the last-read value back via the dedicated etag field on the Update / Delete request; the server rejects the mutation if the stored etag differs.

View as Markdown

The McpService object

{
  "name": "string",
  "owner": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "config": {
    "source_connection": {},
    "include_tool_selectors": [
      "string"
    ],
    "rate_limits": [
      {}
    ]
  },
  "etag": "string"
}

Get

GET /api/2.1/unity-catalog/{name=mcp-services/*}

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.

API scopes: unity-catalog

Parameters

namestringpath

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

Response

Returns the McpService object.

View as Markdown

Response

{
  "name": "string",
  "owner": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "config": {
    "source_connection": {},
    "include_tool_selectors": [
      "string"
    ],
    "rate_limits": [
      {}
    ]
  },
  "etag": "string"
}

List

GET /api/2.1/unity-catalog/mcp-services

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.

API scopes: unity-catalog

Parameters

parentstringquery

Name of the parent schema to list within, as schemas/{catalog}.{schema}. Each {...} component is capped at 255 characters individually.

page_sizeint32query

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.

Constraints: <= 100

page_tokenstringquery

Opaque pagination token from a previous request.

viewstringquery

View selector controlling which fields are populated per row. FULL returns the full representation of the service; BASIC returns a more compact version. Defaults to BASIC when unset.

Values: VIEW_UNSPECIFIED, FULL, BASIC

Response

Returns a list of McpService objects.

View as Markdown

Response

{
  "mcp_services": [
    {
      "name": "string",
      "owner": "string",
      "effective_owner": "string",
      "metastore_id": "string",
      "create_time": "string",
      "created_by": "string",
      "update_time": "string",
      "updated_by": "string",
      "comment": "string",
      "config": {},
      "etag": "string"
    }
  ],
  "next_page_token": "string"
}

Create

POST /api/2.1/unity-catalog/mcp-services

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. The caller supplies the leaf 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.

API scopes: unity-catalog

Parameters

parentstringquery

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

mcp_service_idstringquery

Name for the MCP service, e.g. "my_mcp_service".

Request body

mcp_serviceobject

The MCP service to create. The server populates name from parent + mcp_service_id; clients should leave it unset.

Show child attributesHide child attributes

namestring

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.

ownerstring

The owner of the MCP service. Write-only; read owner via effective_owner.

effective_ownerstring

The resolved owner of the MCP service. Falls back to the caller's identity when owner is not explicitly set on creation.

metastore_idstring

Metastore hosting the MCP service.

create_timestring

When the MCP service was created.

created_bystring

Creator identity.

update_timestring

When the MCP service was last modified.

updated_bystring

Identity of the last updater.

commentstring

User-provided description.

Constraints: <= 65536 characters

configobject

Operational configuration: connection, tool selectors, rate limit. Required on CreateMcpService; on UpdateMcpService it is required only when config (or a config.* subpath) appears in update_mask.

Show child attributesHide child attributes

source_connectionobjectRequired

UC Connection referencing the MCP server.

Show child attributesHide child attributes

namestring

Name of the UC connection that hosts the MCP server, as connections/{catalog}.{schema}.{connection}.

is_deletedboolean

include_tool_selectorsarray of string

Glob or exact-match patterns selecting which tools from the MCP server to expose. Prefix match for patterns with *, exact match otherwise. An empty list means all tools are included. Per-element max 256 chars.

rate_limitsarray of object

Per-principal rate limits applied to tool invocations routed through this MCP service. Repeated to support per-USER / USER_GROUP / SERVICE_PRINCIPAL / SERVICE / USER_DEFAULT scopes simultaneously, mirroring the ModelServiceConfig.rate_limits shape. Empty when no rate limit is configured.

Show child attributesHide child attributes

keystring

Scope key. Determines whether principal is required.

Values: RATE_LIMIT_KEY_USER, RATE_LIMIT_KEY_USER_GROUP, RATE_LIMIT_KEY_SERVICE_PRINCIPAL, RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, RATE_LIMIT_KEY_REQUEST_TAG

renewal_periodstring

Renewal period.

Values: RATE_LIMIT_RENEWAL_PERIOD_MINUTE, RATE_LIMIT_RENEWAL_PERIOD_HOUR

principalstring

Principal this limit applies to: user email, group name, or service principal application ID. Required unless key is RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, or RATE_LIMIT_KEY_REQUEST_TAG (which must not set a principal).

requestsint64

Max requests allowed within a renewal period. Leave unset for no request limit.

tokensint64

Max tokens allowed within a renewal period. Leave unset for no token limit.

request_tag_keystring

Request tag key this limit applies to. Required when key is RATE_LIMIT_KEY_REQUEST_TAG, forbidden otherwise.

request_tag_valuestring

Request tag value this limit applies to. Only valid when key is RATE_LIMIT_KEY_REQUEST_TAG. Leave unset to apply the limit to every value of request_tag_key (an any-value default); a set value is a specific override for that value.

etagstring

Optimistic concurrency control token. Server-generated from the entity's state and returned on every read. To use it as an if-match precondition on a mutation, echo the last-read value back via the dedicated etag field on the Update / Delete request; the server rejects the mutation if the stored etag differs.

Response

Returns the McpService object.

View as Markdown

Request

{
  "mcp_service": {
    "name": "string",
    "owner": "string",
    "effective_owner": "string",
    "metastore_id": "string",
    "create_time": "string",
    "created_by": "string",
    "update_time": "string",
    "updated_by": "string",
    "comment": "string",
    "config": {},
    "etag": "string"
  }
}

Response

{
  "name": "string",
  "owner": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "config": {
    "source_connection": {},
    "include_tool_selectors": [
      "string"
    ],
    "rate_limits": [
      {}
    ]
  },
  "etag": "string"
}

Update

PATCH /api/2.1/unity-catalog/{mcp_service.name=mcp-services/*}

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.

API scopes: unity-catalog

Parameters

mcp_serviceobjectpath

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.

Show child attributesHide child attributes

namestring

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.

ownerstring

The owner of the MCP service. Write-only; read owner via effective_owner.

effective_ownerstring

The resolved owner of the MCP service. Falls back to the caller's identity when owner is not explicitly set on creation.

metastore_idstring

Metastore hosting the MCP service.

create_timestring

When the MCP service was created.

created_bystring

Creator identity.

update_timestring

When the MCP service was last modified.

updated_bystring

Identity of the last updater.

commentstring

User-provided description.

Constraints: <= 65536 characters

configobject

Operational configuration: connection, tool selectors, rate limit. Required on CreateMcpService; on UpdateMcpService it is required only when config (or a config.* subpath) appears in update_mask.

Show child attributesHide child attributes

source_connectionobjectRequired

UC Connection referencing the MCP server.

Show child attributesHide child attributes

namestring

Name of the UC connection that hosts the MCP server, as connections/{catalog}.{schema}.{connection}.

is_deletedboolean

include_tool_selectorsarray of string

Glob or exact-match patterns selecting which tools from the MCP server to expose. Prefix match for patterns with *, exact match otherwise. An empty list means all tools are included. Per-element max 256 chars.

rate_limitsarray of object

Per-principal rate limits applied to tool invocations routed through this MCP service. Repeated to support per-USER / USER_GROUP / SERVICE_PRINCIPAL / SERVICE / USER_DEFAULT scopes simultaneously, mirroring the ModelServiceConfig.rate_limits shape. Empty when no rate limit is configured.

Show child attributesHide child attributes

keystring

Scope key. Determines whether principal is required.

Values: RATE_LIMIT_KEY_USER, RATE_LIMIT_KEY_USER_GROUP, RATE_LIMIT_KEY_SERVICE_PRINCIPAL, RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, RATE_LIMIT_KEY_REQUEST_TAG

renewal_periodstring

Renewal period.

Values: RATE_LIMIT_RENEWAL_PERIOD_MINUTE, RATE_LIMIT_RENEWAL_PERIOD_HOUR

principalstring

Principal this limit applies to: user email, group name, or service principal application ID. Required unless key is RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, or RATE_LIMIT_KEY_REQUEST_TAG (which must not set a principal).

requestsint64

Max requests allowed within a renewal period. Leave unset for no request limit.

tokensint64

Max tokens allowed within a renewal period. Leave unset for no token limit.

request_tag_keystring

Request tag key this limit applies to. Required when key is RATE_LIMIT_KEY_REQUEST_TAG, forbidden otherwise.

request_tag_valuestring

Request tag value this limit applies to. Only valid when key is RATE_LIMIT_KEY_REQUEST_TAG. Leave unset to apply the limit to every value of request_tag_key (an any-value default); a set value is a specific override for that value.

etagstring

Optimistic concurrency control token. Server-generated from the entity's state and returned on every read. To use it as an if-match precondition on a mutation, echo the last-read value back via the dedicated etag field on the Update / Delete request; the server rejects the mutation if the stored etag differs.

update_maskstringquery

The list of fields to update. The framework validates each path against the mcp_service field above. Wildcard paths (paths: ["*"]) are not supported; list each field path explicitly.

etagstringquery

If-match precondition: when set, the update proceeds only if the current server-side etag matches. Empty means an unconditional update.

Response

Returns the McpService object.

View as Markdown

Response

{
  "name": "string",
  "owner": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "config": {
    "source_connection": {},
    "include_tool_selectors": [
      "string"
    ],
    "rate_limits": [
      {}
    ]
  },
  "etag": "string"
}

Delete

DELETE /api/2.1/unity-catalog/{name=mcp-services/*}

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.

API scopes: unity-catalog

Parameters

namestringpath

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

etagstringquery

If-match precondition: when set, the delete proceeds only if the current server-side etag matches. Empty means unconditional delete.

View as Markdown

Response

{}