Conecte agentes a ferramentas com serviços MCP

Um serviço MCP é um recurso protegível do Unity Catalog que fornece uma ferramenta hospedada no Databricks ou registra um servidor MCP externo e governa como os agentes a utilizam. Você o endereça pelo seu nome de três níveis, catalog.schema.mcp_service, e o invoca por meio do Unity Gateway, o plano de controle para governar o tráfego de AI.

Registrar um servidor MCP como um objeto protegível do Unity Catalog significa que ele é gerenciado com as mesmas primitivas que protegem seus outros ativos do Unity Catalog. Isso inclui permissões para controlar quem pode invocá-lo, seleção de ferramentas para limitar quais ferramentas ele expõe, políticas de serviço para permitir ou negar chamadas de ferramentas individuais, e log de auditoria e uso para rastrear cada invocação.

nota

Os serviços MCP são uma das várias maneiras de conectar agentes a MCPs e ferramentas externos, e a recomendada quando o serviço publica um servidor MCP. Para o conjunto completo de opções, incluindo OAuth gerenciado, o proxy de conexões do Unity Catalog e a chamada direta de APIs REST, consulte essa visão geral.

Existem duas maneiras de usar os Serviços MCP:

Abordagem	Usar quando
Use um Serviço MCP fornecido pela Databricks	Você deseja uma ferramenta de workspace integrada ou uma ferramenta comum de software como serviço (SaaS), como Slack, GitHub ou Google Drive, com configuração zero. Nenhum servidor para hospedar e nenhuma conexão para criar.
Registrar seu próprio servidor MCP externo	Você tem um servidor MCP auto-hospedado ou de terceiros para governar como um securable do Unity Catalog.

Abordagem	Usar quando
Use um Serviço MCP fornecido pela Databricks	Você deseja uma ferramenta de workspace integrada ou uma ferramenta comum de software como serviço (SaaS), como Slack, GitHub ou Google Drive, com configuração zero. Nenhum servidor para hospedar e nenhuma conexão para criar.
Registrar seu próprio servidor MCP externo	Você tem um servidor MCP auto-hospedado ou de terceiros para governar como um securable do Unity Catalog.

Requisitos

• Um workspace habilitado para o Unity Catalog.

• Um workspace em uma região onde o Model Serving é compatível. Consulte disponibilidade de recursos de servindo modelo.

Como funciona

Um agente chama um MCP serviço por meio de sua URL do Unity Gateway, e cada chamada flui pelo mesmo caminho governado:

1. Invoke : O agente envia uma solicitação MCP para a URL do Unity Gateway do serviço, autenticada com a identidade Databricks do chamador.
2. Autorizar e governar : O gateway verifica se o chamador tem EXECUTE no Serviço MCP no Unity Catalog. O serviço expõe somente as ferramentas que você selecionou e avalia qualquer política de serviço anexada, que pode permitir, negar ou exigir aprovação para a chamada.
3. Executar a ferramenta : para um serviço fornecido pelo Databricks, o Databricks executa a ferramenta usando a identidade do chamador ou credenciais gerenciadas. Para um servidor externo registrado, o Databricks encaminha a solicitação por meio de sua conexão HTTP e gerencia as credenciais do servidor.
4. Registre o uso, a auditoria e os rastreamentos : cada invocação é registrada em tabelas do sistema, para que você possa monitorar o uso e auditar a atividade ao longo do tempo.

Serviços MCP fornecidos pela Databricks

A Databricks fornece serviços MCP prontos para uso para ferramentas de workspace e aplicativos SaaS comuns. Para serviços disponíveis, configuração e limitações, consulte Serviços MCP fornecidos pela Databricks.

Descobrir as ferramentas de um serviço e ler seus resultados

Cada serviço MCP expõe um conjunto diferente de ferramentas, portanto, descubra-as em Runtime em vez de codificar nomes fixos. Chame tools/list (ou DatabricksMCPClient.list_tools()) para obter o nome, a descrição e o esquema de entrada de cada ferramenta. Consulte Usar servidores MCP em agentes personalizados.

Leia o resultado de uma chamada de ferramenta a partir do campo result. Sua forma depende se a ferramenta define uma saída estruturada:

• Saída tipada. Uma ferramenta pode anunciar um outputSchema e retornar um objeto JSON tipado em structuredContent. Quando structuredContent estiver presente, use-o diretamente. Não requer análise. Algumas ferramentas do Databricks, como as ferramentas do Genie, funcionam desta forma.
• Saída de texto. Quando não houver structuredContent, leia os blocos de texto. O primeiro bloco contém um documento JSON, portanto, analise result.content[0].text como JSON.
• Nenhum. O MCP não requer um esquema de saída. Quando uma ferramenta não define nenhum, inspecione uma resposta de amostra para conhecer seus campos de saída.

Por exemplo, system.ai.google_calendar expõe ferramentas de leitura como calendar_event_list, cujo resultado JSON tem uma matriz items de eventos (cada um com id, summary, start, end, status, location e links). As ferramentas e os formatos de resultado de um serviço diferente diferem totalmente, portanto, sempre confirme com tools/list e uma chamada de amostra.

nota

Serviços integrados gerenciam seus próprios escopos OAuth. Um serviço pode expor apenas um subconjunto de leitura de suas ferramentas por default quando sua política de serviço integrada bloqueia gravações.

Registrar um servidor MCP externo

Para qualquer servidor MCP externo não coberto pelo OAuth gerenciado ou pelos serviços MCP fornecidos pela Databricks, registre-o como um serviço MCP para governá-lo como um item protegível do Unity Catalog. Consulte registro um servidor MCP externo.

Autenticação e segurança

O Databricks usa proxies MCP gerenciados e conexões HTTP do Unity Catalog para lidar com a autenticação em servidores MCP externos de forma segura.

• Autenticação de principal compartilhado : Todos os usuários compartilham as mesmas credenciais ao acessar o serviço externo. Isso inclui tokens Bearer, OAuth Machine-to-Machine (M2M) e autenticação compartilhada OAuth User-to-Machine. Use isso quando o serviço externo não exigir acesso específico do usuário, ou quando uma única account de serviço for suficiente.
• Autenticação por usuário (OAuth U2M Por Usuário) : Cada usuário se autentica com suas próprias credenciais. O serviço externo recebe solicitações em nome do usuário individual, permitindo controle de acesso específico do usuário, auditoria e responsabilidade. Use isso ao acessar recursos específicos do usuário, como os repository do GitHub de um usuário, mensagens do Slack ou calendário.

A Databricks lida com fluxos OAuth e refresh de tokens, portanto, os usuários finais não veem os tokens. Você visualiza e gerencia suas conexões MCP externas juntamente com seus endpoints de LLM a partir do Unity Gateway. Para obter instruções de configuração detalhadas para cada método de autenticação, consulte HTTP connections.

Habilitar acesso por usuário (acesso em nome do usuário)

Alguns serviços leem dados que pertencem a um usuário específico, como seu calendário ou email. Para esses serviços, use OAuth por usuário para que cada chamada seja executada como o usuário que a fez, não como uma identidade compartilhada. Isso se aplica a serviços system.ai.* integrados como system.ai.google_calendar, system.ai.gmail e system.ai.microsoft_365, e a serviços externos que você registra com autenticação por usuário.

Para configurar o acesso 'em nome de' a partir de um agente:

1. Certifique-se de que o usuário que chama possa invocar o serviço. Invocar qualquer serviço MCP requer duas coisas:

   • EXECUTE no serviço.
   • USE CATALOG e USE SCHEMA no seu catálogo e esquema pai. EXECUTE por si só não é suficiente, porque o Unity Catalog também verifica a cadeia pai (consulte Conceder acesso a colegas de equipe).

   Como você concede essas permissões depende do serviço:

   • Serviços system.ai.* integrados: Usuários da account já possuem esses privilégios em system e system.ai por default, portanto, geralmente não é necessário conceder nada.
   • Serviços personalizados em seu próprio catálogo e esquema: Conceda ao usuário ou grupo chamador as permissões apropriadas (não apenas a service principal do Databricks do aplicativo) a partir da tab Permissões de cada item protegível no Explorador de Catálogo, ou com a API REST. DDL SQL não está disponível para serviços MCP.

   Para conceder com a API REST, substitua pelo seu próprio <catalog>.<schema>.<service>:

   Bash

   databricks api patch "/api/2.1/unity-catalog/permissions/mcp_service/<catalog>.<schema>.<service>" \
     --json '{ "changes": [ { "principal": "data-team", "add": ["EXECUTE"] } ] }'
   databricks api patch "/api/2.1/unity-catalog/permissions/catalog/<catalog>" \
     --json '{ "changes": [ { "principal": "data-team", "add": ["USE_CATALOG"] } ] }'
   databricks api patch "/api/2.1/unity-catalog/permissions/schema/<catalog>.<schema>" \
     --json '{ "changes": [ { "principal": "data-team", "add": ["USE_SCHEMA"] } ] }'

2. Adicione o escopo de API de usuário ai-gateway ao seu aplicativo para que o token de usuário encaminhado possa alcançar o serviço. Declare user_api_scopes: [ai-gateway] no recurso do aplicativo e chame o serviço com o cliente por usuário (get_user_workspace_client()). Consulte Autenticar em serviços MCP e Criar um agente e implantá-lo no Databricks Apps.

3. Cada usuário dá seu consentimento uma vez. Na primeira vez que um usuário chama o serviço, ele deve concluir um login OAuth único. Seu aplicativo recebe um link de login para mostrar ao usuário, ou o usuário pode abrir o serviço no Catalog Explorer e clicar em Login .

nota

Você não pode conceder este acesso EXECUTE por meio de um bundle. Um recurso uc_securable do Declarative Automation Bundles oferece suporte apenas a protegíveis VOLUME, TABLE, FUNCTION e CONNECTION, não a serviços MCP, portanto, você deve conceder EXECUTE separadamente, com a interface do usuário ou a API REST acima. Atenção: databricks bundle validate não sinaliza a concessão ausente, portanto, o agente pode ser implantado corretamente e falhar apenas quando chamar o serviço pela primeira vez.

Rede

Os agentes nunca se conectam diretamente ao servidor MCP. O Unity Gateway resolve a conexão do Unity Catalog do serviço, anexa as credenciais gerenciadas e faz a solicitação de saída. Como os serviços MCP são executados em conexões HTTP do Unity Catalog, essa solicitação é roteada pelo plano de compute serverless do seu workspace como qualquer outra conexão HTTP, e os mesmos controles de rede se aplicam.

Permitir um servidor MCP em uma política de rede

Se o seu workspace usa controle de saída serverless com Acesso restrito , adicione o nome de domínio totalmente qualificado (FQDN) do servidor MCP à lista Domínios permitidos na política. Consulte Gerenciar políticas de rede para controle de saída serverless.

Isso se aplica aos serviços system.ai.* fornecidos pela Databricks, bem como aos servidores que você mesmo registra. Cada serviço fornecido pela Databricks alcança seu próprio destino, portanto, permita os destinos para os serviços que você utiliza.

Considere os seguintes pontos ao configurar a política:

• Encontre o destino na conexão e, em seguida, confirme com os logs. O FQDN geralmente é o host da URL do servidor MCP na conexão do Unity Catalog do serviço, mas um serviço pode alcançar um host adicional. As conexões de saída negadas são registradas na tabela do sistema system.access.outbound_network, a maneira mais rápida de encontrar qualquer host que você ainda precise adicionar. Consulte Referência da tabela do sistema de eventos de acesso à rede.
• Destinos bloqueados sempre se aplicam. Um host nos destinos bloqueados da política é negado mesmo com Acesso total . Consulte Bloquear destinos de internet.
• O modo de execução de teste cobre o tráfego MCP apenas em Todos os produtos. Selecionar a opção de execução de teste do Databricks SQL ou servindo modelo de AI não coloca o tráfego do serviço MCP em execução de teste. Consulte Aplicação de políticas.

Quando uma política nega uma chamada, a solicitação falha com um erro de permissão que nomeia o host bloqueado, como Access to <fqdn> is denied because of serverless network policy.

Acesse um servidor MCP de forma privada

Como o tráfego do MCP é roteado pelo seu plano de compute serverless, você protege o caminho de saída da mesma forma que qualquer outra conexão HTTP.

O Private Service Connect para um servidor MCP não é compatível com as conexões HTTP que dão suporte aos serviços MCP. Para limitar quais chamadores alcançam seu servidor, adicione os IPs de saída serverless do Databricks à lista de permissões (allowlist) em seu firewall. Consulte Configuração de firewall de compute serverless.

Limitações

As seguintes limitações se aplicam aos serviços MCP:

• SQL DDL para Serviços MCP (por exemplo, CREATE MCP SERVICE) não está disponível. Crie e gerencie Serviços MCP com a UI ou a API REST.

• Você pode registrar apenas servidores MCP externos como seu próprio serviço MCP. O registro de fontes de entidade do Genie, Apps ou Unity Catalog como um serviço MCP não é suportado no momento.

• A Databricks também fornece serviços MCP integrados para ferramentas de workspace e SaaS.

• A seleção de ferramentas suporta padrões de prefixo (get_*) e de correspondência exata. Padrões de exclusão (por exemplo, !delete_*) não são suportados.

• A Pesquisa Global do Unity Catalog não exibe Serviços MCP.

• Servidores MCP externos estão disponíveis apenas em regiões onde o Model Serving é suportado, incluindo o uso no AI Playground, Genie Code e Chat no Genie. Consulte disponibilidade de recursos de servindo modelo.

• A conectividade privada para recursos em sua VPC (Virtual Private Cloud) usando o Private Service Connect não é suportada. Entre em contato com sua equipe de suporte se precisar desta funcionalidade. Consulte Acesse um servidor MCP de forma privada.

Próximos passos

• Serviços MCP fornecidos pelo Databricks para ferramentas de workspace e SaaS prontas para uso.
• Registrar um servidor MCP externo para registrar e invocar um servidor MCP externo.
• Gerencie um serviço MCP para restringir ferramentas e aplicar políticas de serviço.
• Use servidores MCP em agentes personalizados para chamar um serviço MCP programaticamente a partir do código do agente, com exemplos para o OpenAI Agents SDK, LangGraph e Model Serving.
• Conecte MCPs a assistentes de AI e agentes de codificação para conectar agentes de codificação e assistentes de AI.
• Monitore toda a atividade de IA usando a tabela de rastreamento unificada para monitorar, depurar e auditar toda a atividade de MCP a partir de um único local.
• Governança de AI com o Unity Gateway para governar servidores MCP e LLM Endpoint a partir de um local central.