Gerenciar um serviço MCP

Use o Unity Catalog e o Unity Gateway para controlar as ferramentas, as chamadas, o acesso e o uso de um serviço MCP. Você pode governar serviços MCP registrados e fornecidos pela Databricks. A seleção de ferramentas se aplica apenas a serviços registrados. Os serviços fornecidos pela Databricks possuem ferramentas gerenciadas pela plataforma.

A tabela a seguir mapeia cada meta de governança para o controle que a aborda. Selecione uma meta para os passos.

Objetivo	Controle
Limitar quais ferramentas são expostas	Seleção de ferramentas
Permitir, bloquear ou exigir aprovação para chamadas	Políticas de serviço
Controlar quais provedores um serviço pode acessar	Política de rede
Controlar quem pode invocar um serviço	Privilégios do Unity Catalog
Controlar quais clientes podem se conectar	Controles de aplicativos OAuth e agentes
Limitar o volume de chamadas	Rate limits
Monitorar o uso e a atividade	Uso, auditoria e rastreamento

Objetivo	Controle
Limitar quais ferramentas são expostas	Seleção de ferramentas
Permitir, bloquear ou exigir aprovação para chamadas	Políticas de serviço
Controlar quais provedores um serviço pode acessar	Política de rede
Controlar quem pode invocar um serviço	Privilégios do Unity Catalog
Controlar quais clientes podem se conectar	Controles de aplicativos OAuth e agentes
Limitar o volume de chamadas	Rate limits
Monitorar o uso e a atividade	Uso, auditoria e rastreamento

Limitar quais ferramentas são expostas

Por default, um serviço MCP registrado expõe todas as ferramentas do seu servidor. Selecione um subconjunto durante o registro ou atualize-o posteriormente. Um seletor terminado em * corresponde a um prefixo (get_*). Outros seletores correspondem a um nome exato de ferramenta (search_repositories).

UI

Para expor apenas ferramentas de leitura ao efetuar o registro de um serviço MCP:

1. Em AI Gateway > MCPs , começar o registro do serviço MCP.
2. Em Tools , selecione Advanced e insira get_* para incluir ferramentas cujos nomes comecem com get_. Para selecionar ferramentas individuais, escolha Select manually .
3. Deixe a opção Incluir automaticamente ferramentas adicionadas a este servidor no futuro desativada se novas ferramentas precisarem ser revisadas antes de se tornarem disponíveis.

REST API

Para alterar a seleção de ferramentas após a criação, defina include_tool_selectors com uma solicitação de PATCH. Restringir um serviço a somente get_* ferramentas:

Bash

databricks api patch \
  "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp?update_mask=config.include_tool_selectors" \
  --json '{
    "config": {
      "include_tool_selectors": ["get_*"]
    }
  }'

Reset para disponibilizar todas as ferramentas definindo include_tool_selectors para uma lista vazia.

Ferramentas não selecionadas não aparecem em tools/list. Um tools/call para uma ferramenta não selecionada retorna:

JSON

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

Allow, block, or require approval for calls

info

Beta

As políticas de serviço estão em Beta. Um administrador de account deve habilitar os recursos beta do Unity Gateway na página Prévias do console da account. Consulte Gerenciar prévias do Databricks.

Uma política de serviço avalia uma chamada de ferramenta antes da execução (ON CALL) e pode avaliar seu resultado (ON RESULT). Ela pode permitir, bloquear ou exigir aprovação para uma chamada sem alterar a lista de ferramentas. Você precisa de MANAGE no serviço para anexar uma política. Consulte Criar e anexar uma política de serviço para conhecer todos os requisitos de configuração.

Exemplo: Bloquear PII em chamadas e resultados de ferramentas

Use a política integrada Sensitive Data Detection para bloquear chamadas que contenham informações pessoalmente identificáveis (PII):

1. Na barra lateral do workspace, clique em AI Gateway . Na tab MCPs , selecione o serviço.
2. Abra Policies > New policy e insira um nome, como block_sensitive_data.
3. Em Guardrail type , selecione 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. Em Fase , selecione Entrada e Saída para inspecionar os argumentos e os resultados da ferramenta.
6. Defina o Rank e clique em Criar política .

A política se aplica a todos os usuários account no serviço durante a versão Beta. Para ver o comportamento da categoria e mais opções, consulte Detectar dados confidenciais com uma política de serviço.

Exemplo: Negar uma ferramenta a um agente específico

Para um serviço MCP registrado que expõe push_files, esta função personalizada nega essa ferramenta quando o agente atuante tem uma ID de cliente OAuth específica. Substitua <agent-oauth-client-id> pela ID de cliente do agente e main.governance por um esquema onde você possa criar funções:

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. Execução o SQL em um editor SQL para criar a função.
2. Em AI Gateway > MCPs , abra o serviço registrado e selecione Policies > New policy .
3. Digite um nome, selecione Personalizado em Tipo de barreira de segurança e selecione a função. Defina a Classificação e clique em Criar política .
4. Chame push_files por meio desse agente para verificar a negação. Uma chamada por meio de um agente diferente deve continuar sendo permitida por esta política.

Este exemplo identifica o agente apenas para chamadas em nome de (on-behalf-of) que incluem seu ID do cliente OAuth. A ferramenta ainda aparece em tools/list. Para removê-la para todos os chamadores, use a seleção de ferramentas. Consulte a referência de função de política para os campos do ator e a configuração de política personalizada para privilégios de função. Para obter uma política de gravação do GitHub integrada, siga Governar o acesso ao GitHub MCP de um agente de codificação.

Controlar quais provedores um serviço pode acessar

A serverless network policy determina quais provedores um serviço MCP pode acessar. Isso se aplica a servidores externos registrados e aplicativos conectados fornecidos pela Databricks. Com Restricted access , os destinos públicos são bloqueados até que você adicione seus domínios a Allowed domains .

Por exemplo, se um servidor MCP registrado usar https://mcp.example.com/mcp, um administrador de account poderá permiti-lo na política de rede do workspace:

1. No console da account, abra Security > Networking > Context-based ingress & egress control .
2. Abra a política associada ao workspace. Se o workspace não tiver atribuição explícita, abra a política default.
3. Em Egress , selecione Restricted access to specific destinations . Em Allowed domains , clique em Add destination e insira mcp.example.com.
4. Clique em Update . Permita que a alteração seja propagada e, em seguida, invoque uma ferramenta no MCP serviço. Se outro host necessário estiver bloqueado, verifique os logs de rede de saída e adicione esse host também.

Consulte Gerenciar políticas de rede para obter detalhes sobre a aplicação de políticas e Permitir um servidor MCP em uma política de rede para destinos de MCP.

Uma chamada bloqueada relata o destino, por exemplo:

Text

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

Uma conexão do Unity Catalog não permite automaticamente o seu destino em uma política de rede restrita. A inclusão implícita em lista de permissões para conexões do Unity Catalog foi preterida. Para destinos privados, consulte Acessar um servidor MCP de forma privada.

Controlar quem pode invocar um serviço

Os chamadores precisam de EXECUTE no serviço MCP, além de USE CATALOG e USE SCHEMA em seus pais. Para compartilhar um serviço registrado, como main.default.my_mcp, com data-team:

1. In AI Gateway > MCPs , open the serviço 's tab tab.
2. Clique em GRANT , selecione data-team e EXECUTE e clique em GRANT .
3. Confirme se o grupo pode usar o catálogo pai e o esquema. Consulte Conceder acesso a um serviço MCP para conhecer as os passos de UI e API.

Revise as concessões amplas existentes antes de restringir os chamadores. Os serviços fornecidos pelo Databricks podem herdar uma concessão default de EXECUTE em system.ai. Por exemplo, para conceder acesso a serviços aprovados, aplique uma tag governada como access_status = approved, e crie uma política GRANT:

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');

A policy concede acesso a serviços com tags. Para manter os serviços sem tags inacessíveis, remova qualquer GRANT amplo que também permita o acesso a eles. Para ver os passos de tag e o impacto de remover o GRANT de schema default, siga Govern models and MCPs with GRANT policies. Um GRANT do Unity Catalog não permite saída de rede (egress).

Controlar quais clientes podem se conectar

Quando um cliente MCP externo usa um aplicativo Databricks OAuth dedicado, um administrador account pode gerenciar esse aplicativo em Configurações > Conexões de aplicativos no console da conta. Por exemplo, crie uma conexão de aplicativo para um agente de codificação aprovado e, em seguida, configure o agente com seu ID de cliente. A remoção da conexão do aplicativo desativa esse cliente OAuth em toda a account. Consulte Conectar clientes usando OAuth, Habilitar ou desabilitar aplicativos OAuth e Autorização de usuário do OAuth para obter informações básicas sobre tokens e consentimento.

Para um agente agindo em nome de um usuário, uma política de serviço personalizada pode verificar sua ID de cliente OAuth para negar uma ferramenta específica ou chamada de serviço. O exemplo de push_files acima mostra o padrão por ferramenta. Essa verificação funciona apenas quando a chamada contém a ID de cliente do agente. Clientes configurados por meio da CLI do Unity Gateway usam um login da CLI do Databricks em vez de um aplicativo OAuth separado. Para restringir os IPs de cliente de entrada para um Workspace, consulte Listas de acesso IP para Workspace.

Limitar o volume de chamadas

Defina limites de taxa para proteger um servidor externo e controlar o volume de chamadas. Por exemplo, limite o serviço a 60 chamadas de ferramenta por minuto entre todos os chamadores:

1. Em Gateway de AI > MCPs , abra o serviço.
2. Em Overview , localize Rate limits e clique em Set up (ou Edit se os limites já existirem).
3. Digite 60 no campo QPM do serviço e clique em Salvar .

Os limites de taxa de MCP se aplicam a tools/call solicitações e usam queries por minuto (QPM), e não tokens. Uma chamada que excede o limite retorna HTTP 429. Consulte Aplicar limites de taxa aos serviços de modelo e MCP para obter limites por usuário e por grupo.

Monitorar uso e atividade

O Unity Gateway registra a atividade do serviço MCP nestas tabelas do sistema:

• Usage and dashboard : query system.ai_gateway.usage com service_type = 'MCP_SERVICE' para ver o volume de chamadas, os erros e a latência, ou use o painel de uso integrado.
• Audit : Review serviço changes and invocations (mcpCall) in system.access.audit. See Audit logs.
• Rastreamentos : inspecione solicitações de ferramentas, respostas e decisões de política na tabela de rastreamento unificada depois que um administrador account a habilitar para a account.

Por exemplo, conte as chamadas para cada ferramenta do GitHub:

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;

Para ter acesso às tabelas do sistema, consulte Monitor account activity with system tables.