Conectar agentes a ferramentas de terceiros com os Serviços MCP

Um serviço MCP é um catálogo do Unity protegível que registra um servidor MCP externo e rege como os agentes o usam. Você o referencia pelo nome de três níveis, catalog.schema.mcp_service, e o invoca por meio do Unity AI Gateway, o plano de controle para governar o tráfego de IA.

Registrar um servidor MCP como um protegível do Catálogo do Unity significa que você o gerencia com os mesmos primitivos que protegem seus outros ativos do Catálogo do Unity. Isso inclui concessõ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 registro em log de auditoria e uso para acompanhar cada invocação.

Há duas maneiras de usar os Serviços MCP:

Requirements

• Um espaço de trabalho habilitado para usar o Unity Catalog.

• Um workspace em uma região em que o Serviço de Modelo tem suporte. Consulte Modelos de disponibilidade de funcionalidades de serviço.

Como funciona

Um agente chama um Serviço MCP por sua URL de Gateway de IA do Unity e cada chamada flui pelo mesmo caminho controlado:

1. Invocar: o agente envia uma solicitação MCP para a URL do Unity AI Gateway do serviço, usando a identidade do Azure Databricks do chamador para autenticação.
2. Autorizar e controlar: o gateway verifica se o chamador tem EXECUTE no Serviço MCP no Catálogo do Unity. O serviço expõe apenas as ferramentas selecionadas e avalia qualquer política de serviço anexada, que pode permitir, negar ou exigir aprovação para a chamada.
3. Proxy com credenciais gerenciadas: a solicitação é encaminhada para o servidor MCP externo por meio da conexão HTTP do serviço. Azure Databricks armazena as credenciais e manipula fluxos OAuth e atualização de token, de modo que o agente nunca as vê.
4. Uso, auditoria e rastreamentos de log: cada invocação é registrada em tabelas do sistema, para que você possa monitorar a atividade de uso e auditoria ao longo do tempo.

Serviços MCP fornecidos pelo Databricks

Azure Databricks fornece serviços MCP prontos para uso no system.ai esquema para aplicativos SaaS comuns, para que os agentes possam acessar essas ferramentas sem hospedar ou registrar seu próprio servidor MCP. Cada um é um serviço MCP integrado que você acessa pelo nome dele no Unity Catalog. Para dar acesso a um agente, conceda EXECUTE no serviço (por exemplo, system.ai.github). Não é necessário configurar a conexão. Os serviços internos são fornecidos com ferramentas gerenciadas por plataforma e uma política de serviço interna, como uma para bloquear operações de gravação. Você os rege com concessões em vez de com funções de política ou seleção de ferramentas personalizadas.

Para Google Drive, Gmail, Google Calendar ou Microsoft 365, esses serviços internos manipulam o OAuth para você, sem necessidade de registro de aplicativo.

Invocar um Serviço MCP embutido

Acesse um serviço incorporado usando a URL do Unity AI Gateway, com o nome completamente qualificado no caminho. Use o nome exatamente como aparece, com seus pontos e sublinhados, e não o codifique por URL:

https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<mcp-service>

Para chamar o serviço a partir do código do agente, aponte um DatabricksMCPClient ou um framework para agentes para este URL. Veja Usar servidores MCP em Agentes Personalizados.

Descubra as ferramentas de um serviço e leia seus resultados

Cada Serviço MCP expõe um conjunto diferente de ferramentas, então descubra-as em tempo de execução em vez de codificar nomes fixamente. Ligue tools/list (ou DatabricksMCPClient.list_tools()) para obter o nome, descrição e esquema de entrada de cada ferramenta. Veja Usar servidores MCP em Agentes Personalizados.

Leia o resultado de uma chamada de ferramenta a partir do result campo. Sua forma depende de a ferramenta definir ou não a saída estruturada:

• Saída digitada. Uma ferramenta pode anunciar um outputSchema e retornar um objeto JSON tipado em structuredContent. Quando structuredContent estiver presente, use-o diretamente. Não precisa de análise sintética. Algumas ferramentas do Azure Databricks, como as ferramentas Genie, funcionam dessa forma.
• Saída de texto. Quando não houver structuredContent, leia os blocos de texto em vez deles. O primeiro bloco contém um documento JSON, então analise result.content[0].text como JSON.
• Nenhum dos dois. O MCP não requer um esquema de saída. Quando uma ferramenta não define nenhuma, inspecione uma resposta de exemplo para aprender seus campos de saída.

Por exemplo, system.ai.google_calendar expõe ferramentas de leitura como calendar_event_list, cujo resultado JSON possui um items array de eventos (cada um com id, summary, start, end, status, location, e links). As ferramentas e as estruturas dos resultados de outro serviço são totalmente diferentes, então sempre confirme com tools/list e com uma chamada de exemplo.

Registrar um servidor MCP externo

Para qualquer servidor MCP externo que não seja coberto pelo OAuth gerenciado ou pelos Serviços MCP fornecidos pelo Databricks, registre-o como um Serviço MCP para governá-lo como um Unity Catalog protegível. Veja Registrar um servidor MCP externo.

Autenticação e segurança

Azure Databricks usa proxies MCP gerenciados e conexões HTTP do Unity Catalog para gerenciar com segurança a autenticação em servidores MCP externos.

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

Azure Databricks manipula fluxos OAuth e atualização de token, para que os usuários finais não vejam tokens. Você pode visualizar e gerenciar suas conexões MCP externas juntamente com seus endpoints de LLM no Gateway de IA do Unity. Para obter instruções de configuração detalhadas para cada método de autenticação, consulte conexões HTTP.

Habilitar o 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 e-mail. Para esses serviços, use OAuth por usuário para que cada chamada seja executada como o usuário que a fez, e não como uma identidade compartilhada. Isso se aplica a serviços embutidos system.ai.* 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 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 em seu catálogo e esquema parentais. EXECUTE por si só não é suficiente, porque o Unity Catalog também verifica a cadeia hierárquica superior (veja Conceder acesso aos colegas de equipe).

   Como você concede esses itens depende do serviço:

   • Serviços embutidos system.ai.* : Os usuários da conta já possuem esses privilégios ativados system e system.ai por padrão, então geralmente você não precisa conceder nada de especial.
   • Serviços personalizados em seu próprio catálogo e esquema: Conceda ao usuário ou grupo autor da chamada as permissões apropriadas (não apenas à entidade de serviço do aplicativo) na guia Permissões de cada objeto protegível no Explorador de Catálogo ou com a API REST. SQL DDL não está disponível para os Serviços MCP.

   Para conceder com a API REST, substitua a sua <catalog>.<schema>.<service>:

   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 da ai-gateway API do usuário 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()). Veja Autenticar em Serviços MCP e Criar um agente e implantá-lo nos aplicativos Databricks.

3. Cada usuário consente uma vez. Na primeira vez que um usuário chama o serviço, ele deve completar um login OAuth único. Seu app recebe um link de login para mostrar ao usuário, ou o usuário pode abrir o serviço no Explorador de Catálogos e clicar em Login.

Limitations

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

• A DDL do SQL para serviços MCP (por exemplo, CREATE MCP SERVICE) não está disponível. Crie e gerencie serviços MCP com a interface do usuário ou a API REST.
• Você pode registrar apenas servidores MCP externos como seu próprio Serviço MCP. No momento, não há suporte para registrar fontes de entidade do Genie, de Apps ou do Unity Catalog como serviço MCP. Azure Databricks também fornece serviços MCP internos para aplicativos SaaS comuns.
• A seleção de ferramentas dá suporte a padrões de prefixo (get_*) e de correspondência exata. Não há suporte para padrões de exclusão (por exemplo, !delete_*) .
• A Pesquisa Global do Catálogo do Unity não apresenta os Serviços MCP.

As conexões de servidor MCP externo também têm as seguintes limitações:

• Os servidores MCP externos estão disponíveis apenas em regiões em que o Model Serving é compatível, incluindo o uso no AI Playground, no Genie Code e no Chat no Genie. Consulte Modelos de disponibilidade de funcionalidades de serviço.

Próximas Etapas 

• Registre um servidor MCP externo para registrar e invocar um servidor MCP externo.
• Governe um serviço MCP para restringir as 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 SDK OpenAI Agents, LangGraph e Model Serving.
• Conecte MCPs a assistentes de IA e agentes de codificação para conectar agentes de codificação e assistentes de IA.
• Monitore toda a atividade de IA usando a tabela unificada de traços para monitorar, depurar e auditar toda a atividade do MCP em um único lugar.
• Governança de IA com o Unity AI Gateway para gerenciar servidores MCP e endpoints de LLM a partir de um local central.