Mcp Service

View as Markdown

A Unity Catalog securable that registers an MCP server through a Unity Catalog connection and exposes its tools for discovery, authorization, and invocation.

Get an MCP serviceGET /api/2.1/unity-catalog/{name=mcp-services/*}List MCP servicesGET /api/2.1/unity-catalog/mcp-servicesCreate an MCP servicePOST /api/2.1/unity-catalog/mcp-servicesUpdate an MCP servicePATCH /api/2.1/unity-catalog/{name=mcp-services/*}Delete an MCP serviceDELETE /api/2.1/unity-catalog/{name=mcp-services/*}

McpService object

A Unity Catalog securable that registers an MCP server through a Unity Catalog connection and exposes its tools for discovery, authorization, and invocation.

namestringImmutable

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.

effective_ownerstringOutput only

Owner of the MCP service.

metastore_idstringOutput only

Metastore hosting the MCP service.

create_timestringOutput only

Time the MCP service was created.

created_bystringOutput only

Creator identity.

update_timestringOutput only

Time the MCP service was last modified.

updated_bystringOutput only

Identity of the last updater.

commentstring

User-provided description.

Constraints: <= 65536 characters

configobject

Connection, tool selectors, and rate limits. Required on Create. On Update, provide this field when update_mask contains config or one of its subpaths.

Show child attributesHide child attributes

source_connectionobject

Unity Catalog connection referencing the MCP server. Required on Create.

Show child attributesHide child attributes

namestring

Resource name of the Unity Catalog connection used to access the MCP server, in the form connections/{catalog}.{schema}.{connection}.

is_deletedbooleanOutput only

Whether the referenced connection has been deleted. The MCP service keeps the reference so callers can identify the broken dependency; tool invocation fails until the source connection is updated.

include_tool_selectorsarray of string

Tool names or prefix patterns to expose from the MCP server. Use exact tool names or prefix patterns such as read_*. An empty list exposes all tools. At most 1,024 selectors are allowed, and each selector can contain at most 256 characters.

rate_limitsarray of object

Rate limits for tool invocations. Supported scopes are user, group, service principal, the service as a whole, and each user by default. Request and token limits are supported. Empty when no rate limit is configured.

Show child attributesHide child attributes

keystring

Scope of the rate limit. Depending on this value, the limit applies to a principal, the service as a whole, or each user by default.

Values:

• RATE_LIMIT_KEY_USER
• RATE_LIMIT_KEY_USER_GROUP
• RATE_LIMIT_KEY_SERVICE_PRINCIPAL
• RATE_LIMIT_KEY_SERVICE
• RATE_LIMIT_KEY_USER_DEFAULT

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 when key applies to a user, group, or service principal; otherwise it must be unset.

requestsint64

Maximum requests allowed in one renewal period. Leave unset for no request limit. Set to 0 to deny all requests.

tokensint64

Maximum tokens allowed in one renewal period. Leave unset for no token limit. Set to 0 to deny all requests.

etagstringOutput only

Optimistic concurrency token returned on every read. To make an Update or Delete conditional, pass the last-read value in that request's etag field. In REST responses, this value is a base64 string; URL-encode it when setting the etag query parameter.

View as Markdown

The McpService object

{
  "name": "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 an MCP service GA

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

namestringRequiredpath

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",
  "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 MCP services GA

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

Parent schema to list within, in the form schemas/{catalog}.{schema}. Required. 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 the previous response.

viewstringquery

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.

Values:

• VIEW_UNSPECIFIED
• FULL
• BASIC

Response

Returns a list of McpService objects.

View as Markdown

Response

{
  "mcp_services": [
    {
      "name": "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 an MCP service GA

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. 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.

API scopes: unity-catalog

Parameters

parentstringRequiredquery

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

mcp_service_idstringRequiredquery

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

Request body

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

namestringImmutable

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.

commentstring

User-provided description.

Constraints: <= 65536 characters

configobject

Connection, tool selectors, and rate limits. Required on Create. On Update, provide this field when update_mask contains config or one of its subpaths.

Show child attributesHide child attributes

source_connectionobject

Unity Catalog connection referencing the MCP server. Required on Create.

Show child attributesHide child attributes

namestringRequired

Resource name of the Unity Catalog connection used to access the MCP server, in the form connections/{catalog}.{schema}.{connection}.

include_tool_selectorsarray of string

Tool names or prefix patterns to expose from the MCP server. Use exact tool names or prefix patterns such as read_*. An empty list exposes all tools. At most 1,024 selectors are allowed, and each selector can contain at most 256 characters.

rate_limitsarray of object

Rate limits for tool invocations. Supported scopes are user, group, service principal, the service as a whole, and each user by default. Request and token limits are supported. Empty when no rate limit is configured.

Show child attributesHide child attributes

keystringRequired

Scope of the rate limit. Depending on this value, the limit applies to a principal, the service as a whole, or each user by default.

Values:

• RATE_LIMIT_KEY_USER
• RATE_LIMIT_KEY_USER_GROUP
• RATE_LIMIT_KEY_SERVICE_PRINCIPAL
• RATE_LIMIT_KEY_SERVICE
• RATE_LIMIT_KEY_USER_DEFAULT

renewal_periodstringRequired

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 when key applies to a user, group, or service principal; otherwise it must be unset.

requestsint64

Maximum requests allowed in one renewal period. Leave unset for no request limit. Set to 0 to deny all requests.

tokensint64

Maximum tokens allowed in one renewal period. Leave unset for no token limit. Set to 0 to deny all requests.

Response

Returns the McpService object.

View as Markdown

Request

{
  "name": "string",
  "comment": "string",
  "config": {
    "source_connection": {},
    "include_tool_selectors": [
      "string"
    ],
    "rate_limits": [
      {}
    ]
  }
}

Response

{
  "name": "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 an MCP service GA

PATCH /api/2.1/unity-catalog/{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. When changing config.source_connection.name, the MCP service owner must also have USE_CONNECTION on the new connection.

API scopes: unity-catalog

Parameters

namestringRequiredImmutablepath

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.

update_maskstringRequiredquery

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. Wildcard paths such as * are not supported.

etagstringquery

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.

Request body

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.

commentstring

User-provided description.

Constraints: <= 65536 characters

configobject

Connection, tool selectors, and rate limits. Required on Create. On Update, provide this field when update_mask contains config or one of its subpaths.

Show child attributesHide child attributes

source_connectionobject

Unity Catalog connection referencing the MCP server. Required on Create.

Show child attributesHide child attributes

namestringRequired

Resource name of the Unity Catalog connection used to access the MCP server, in the form connections/{catalog}.{schema}.{connection}.

include_tool_selectorsarray of string

Tool names or prefix patterns to expose from the MCP server. Use exact tool names or prefix patterns such as read_*. An empty list exposes all tools. At most 1,024 selectors are allowed, and each selector can contain at most 256 characters.

rate_limitsarray of object

Rate limits for tool invocations. Supported scopes are user, group, service principal, the service as a whole, and each user by default. Request and token limits are supported. Empty when no rate limit is configured.

Show child attributesHide child attributes

keystringRequired

Scope of the rate limit. Depending on this value, the limit applies to a principal, the service as a whole, or each user by default.

Values:

• RATE_LIMIT_KEY_USER
• RATE_LIMIT_KEY_USER_GROUP
• RATE_LIMIT_KEY_SERVICE_PRINCIPAL
• RATE_LIMIT_KEY_SERVICE
• RATE_LIMIT_KEY_USER_DEFAULT

renewal_periodstringRequired

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 when key applies to a user, group, or service principal; otherwise it must be unset.

requestsint64

Maximum requests allowed in one renewal period. Leave unset for no request limit. Set to 0 to deny all requests.

tokensint64

Maximum tokens allowed in one renewal period. Leave unset for no token limit. Set to 0 to deny all requests.

Response

Returns the McpService object.

View as Markdown

Request

{
  "comment": "string",
  "config": {
    "source_connection": {},
    "include_tool_selectors": [
      "string"
    ],
    "rate_limits": [
      {}
    ]
  }
}

Response

{
  "name": "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 an MCP service GA

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

namestringRequiredpath

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

etagstringquery

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.

View as Markdown

Response

{}