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

Um Serviço MCP é um Unity Catalog securável que regista um servidor MCP externo e governa como os agentes o utilizam. Dirige-se a ele pelo seu nome de três níveis, catalog.schema.mcp_service, e invoca-o através do Unity AI Gateway, o plano de controlo para gerir o tráfego de IA.

Registar um servidor MCP como seguro do Unity Catalog significa que o geres com as mesmas primitivas que protegem os teus outros ativos do Unity Catalog. Estas incluem subsídios para controlar quem pode invocá-lo, seleção de ferramentas para limitar as ferramentas que expõe, políticas de serviço para permitir ou negar chamadas individuais de ferramentas, e auditoria e registo de utilização para acompanhar cada invocação.

Existem duas formas de utilizar os Serviços MCP:

Requisitos

• Um espaço de trabalho ativado para o Unity Catalog.

• Um espaço de trabalho numa região onde o Model Serving é suportado. Consulte Disponibilidade de funcionalidades de serviço de modelos.

Como funciona

Um agente chama um Serviço MCP pelo seu URL de Gateway Unity AI, e cada chamada flui pelo mesmo caminho governado:

1. Invocar: O agente envia um pedido MCP para o URL do Gateway Unity AI do serviço, autenticado com a identidade Azure Databricks do chamador.
2. Autorizar e gerir: O gateway verifica se o autor da chamada tem EXECUTE no Serviço MCP no Unity Catalog. O serviço expõe apenas as ferramentas que selecionou e avalia qualquer política de serviço anexada, que pode permitir, negar ou exigir aprovação para a chamada.
3. Proxy com credenciais geridas: O pedido é encaminhado para o servidor MCP externo através da ligação HTTP do serviço. O Azure Databricks armazena as credenciais e gere os fluxos OAuth e a atualização de tokens, por isso o agente nunca as vê.
4. Utilização de logs, auditoria e rastreamentos: Cada invocação é registada em tabelas do sistema, para que possa monitorizar o uso e auditar a atividade ao longo do tempo.

Serviços MCP fornecidos por Databricks

O Azure Databricks fornece Serviços MCP prontos a usar no system.ai esquema para aplicações SaaS comuns, permitindo que os agentes acedam a estas ferramentas sem alojar ou registar o seu próprio servidor MCP. Cada um é um Serviço MCP integrado ao qual acede pelo respetivo nome no Unity Catalog. Para dar acesso a um agente, conceda EXECUTE ao serviço (por exemplo, system.ai.github). Não é necessária configuração de ligação. Os serviços integrados vêm com ferramentas geridas pela plataforma e uma política de serviço incorporada, como uma para bloquear operações de escrita. Governa-as com subsídios em vez de com seleção personalizada de ferramentas ou funções políticas.

Para Google Drive, Gmail, Google Calendar ou Microsoft 365, estes serviços integrados tratam do OAuth por si, sem necessidade de registo na aplicação.

Invocar um Serviço MCP incorporado

Aceda a um serviço integrado através do URL do Unity AI Gateway, com o nome completamente qualificado no caminho. Use o nome exatamente como aparece, com os seus pontos e sublinhas, 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 de agente para este URL. Veja Usar servidores MCP em Agentes Personalizados.

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

Cada Serviço MCP expõe um conjunto diferente de ferramentas, por isso descobre-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. A sua forma depende de a ferramenta definir a saída estruturada:

• Saída digitada. Uma ferramenta pode anunciar um outputSchema e devolver um objeto JSON tipado em structuredContent. Quando structuredContent estiver presente, use-o diretamente. Não precisa de análise. Algumas ferramentas do Azure Databricks, como as ferramentas Genie, funcionam desta forma.
• Saída de texto. Quando não houver structuredContent, leia antes os blocos de texto. O primeiro bloco contém um documento JSON, portanto 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 os seus campos de saída.

Por exemplo, system.ai.google_calendar expõe ferramentas de leitura como calendar_event_list, cujo resultado JSON tem 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 completamente diferentes, por isso confirme sempre com tools/list e uma chamada de exemplo.

Registar um servidor MCP externo

Para qualquer servidor MCP externo não coberto pelo OAuth gerido ou pelos Serviços MCP fornecidos pela Databricks, registe-o como um Serviço MCP para o governar como um Unity Catalog securável. Veja Registar um servidor MCP externo.

Autenticação e segurança

O Azure Databricks utiliza proxies MCP geridos e ligações HTTP do Unity Catalog para gerir a autenticação segura em servidores MCP externos.

• Autenticação principal partilhada: Todos os utilizadores partilham as mesmas credenciais ao aceder ao serviço externo. Isto inclui token Bearer, OAuth Machine-to-Machine (M2M) e OAuth Utilizador-para-Máquina com Autenticação Partilhada. Use isto quando o serviço externo não precisar de acesso específico ao utilizador, ou quando uma única conta de serviço for suficiente.
• Autenticação por utilizador (OAuth U2M Por Utilizador): Cada utilizador autentica-se com as suas próprias credenciais. O serviço externo recebe pedidos em nome do utilizador individual, permitindo controlo de acesso, auditoria e responsabilização específicos do utilizador. Utilize-o ao aceder a recursos específicos do utilizador, como repositórios do GitHub do utilizador, mensagens do Slack ou calendário.

O Azure Databricks trata dos fluxos OAuth e da atualização dos tokens, por isso os utilizadores finais não veem tokens. Visualiza e gere as suas ligações MCP externas juntamente com os endpoints do LLM a partir do Unity AI Gateway. Para instruções de configuração detalhadas para cada método de autenticação, veja Ligações HTTP.

Permitir o acesso por utilizador (acesso em nome do utilizador)

Alguns serviços leem dados que pertencem a um utilizador específico, como o seu calendário ou email. Para estes serviços, use OAuth por utilizador para que cada chamada seja executada como o utilizador que a fez, e não como uma identidade partilhada. Isto aplica-se a serviços incorporados system.ai.* como system.ai.google_calendar, system.ai.gmail, e system.ai.microsoft_365, e a serviços externos que registas com autenticação por utilizador.

Para configurar o acesso em nome de um agente:

1. Certifique-se de que o utilizador que chama pode invocar o serviço. Invocar qualquer Serviço MCP requer duas coisas:

   • EXECUTE no serviço.
   • USE CATALOG e USE SCHEMA no respetivo catálogo e esquema principais. EXECUTE por si só não é suficiente, porque o Unity Catalog também verifica a cadeia hierárquica ascendente (consulte Conceder acesso aos colegas da equipa).

   A forma como concede estas informações depende do serviço:

   • Serviços incorporadossystem.ai.*: Os utilizadores da conta já têm estes privilégios em system e system.ai por defeito, pelo que normalmente não é necessário conceder seja o que for.
   • Serviços personalizados no seu próprio catálogo e esquema: Conceda ao utilizador ou grupo autor da chamada as permissões adequadas (não apenas ao principal de serviço da aplicação) no separador Permissões de cada objeto protegível no Explorador de Catálogo, ou através da API REST. O SQL DDL não está disponível para os Serviços MCP.

   Para conceder acesso através da API REST, substitua pelo seu próprio <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 âmbito da ai-gateway API de utilizador à sua aplicação para que o token de utilizador encaminhado possa chegar ao serviço. Declare user_api_scopes: [ai-gateway] no recurso da aplicação e chame o serviço com o cliente de cada utilizador (get_user_workspace_client()). Veja Autenticar em Serviços MCP e Criar um agente e implementá-lo nas aplicações Databricks.

3. Cada utilizador consente uma vez. Na primeira vez que um utilizador chama o serviço, deve completar um login OAuth único. A sua aplicação recebe um link de login para mostrar ao utilizador, ou o utilizador pode abrir o serviço no Explorador de Catálogos e clicar em Iniciar sessão.

Limitações

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

• SQL DDL para Serviços MCP (por exemplo, CREATE MCP SERVICE) não está disponível. Crie e gere Serviços MCP com a interface ou a API REST.
• Só pode registar servidores MCP externos como o seu próprio Serviço MCP. Registar fontes de entidades Genie, Apps ou Unity Catalog como um Serviço MCP não é atualmente suportado. O Azure Databricks também fornece Serviços MCP incorporados para aplicações SaaS comuns.
• A seleção de ferramentas suporta padrões de prefixo (get_*) e padrões de correspondência exata. Padrões de exclusão (por exemplo, !delete_*) não são suportados.
• O Unity Catalog Global Search não apresenta serviços MCP.

As ligações externas a servidores MCP também apresentam as seguintes limitações:

• Servidores MCP externos estão disponíveis apenas em regiões onde o Model Serving é suportado, incluindo uso no AI Playground, Genie Code e Chat no Genie. Consulte Disponibilidade de funcionalidades de serviço de modelos.

Passos seguintes

• Registar um servidor MCP externo para registar e invocar um servidor MCP externo.
• Governar 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 SDK OpenAI Agents, LangGraph e Model Serving.
• Ligue MCPs a assistentes de IA e agentes de codificação para ligar agentes de codificação e assistentes de IA.
• Monitorizar toda a atividade de IA usando a tabela de traços unificada para monitorizar, depurar e auditar toda a atividade MCP a partir de um só local.
• Governação de IA com Unity AI Gateway para governar servidores MCP e endpoints LLM a partir de uma localização central.