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:

Os Serviços MCP conectam agentes a serviços externos. Para dados do Azure Databricks, use servidores MCP gerenciados; para hospedar suas próprias ferramentas, use um servidor MCP personalizado.

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, exigir aprovação ou transformar 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.

Requirements

• Um espaço de trabalho habilitado para usar o Unity Catalog.
• Para gerenciar um servidor MCP externo como um Serviço MCP, o Unity AI Gateway Beta e a prévia de Servidores MCP Gerenciados precisam estar habilitados na sua conta. Consulte Gerenciar visualizações do Azure Databricks.

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

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 conceder acesso a um agente, conceda EXECUTE ao serviço (por exemplo, system.ai.github)— nenhuma configuração de conexão necessária. 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 SharePoint, esses serviços internos manipulam o OAuth para você, sem necessidade de registro de aplicativo.

Registrar um servidor MCP externo

Registre seu próprio servidor MCP externo como um Serviço MCP em cinco etapas:

1. Crie uma conexão no Unity Catalog com o servidor MCP.
2. Crie o serviço MCP a partir dessa conexão.
3. Autenticar, se a conexão usar OAuth por usuário.
4. Conceda acesso aos seus colegas de equipe.
5. Invoque o serviço e, em seguida, governe-o com políticas de serviço e seleção de ferramentas.

O servidor MCP externo deve usar o mecanismo de transporte HTTP streamable. Você precisa dessas permissões:

• Para criar a conexão, CREATE CONNECTION no esquema em que você a cria.
• Para criar um Serviço MCP, USE CATALOG e USE SCHEMA no catálogo pai e no esquema, CREATE SERVICE no esquema e USE CONNECTION na conexão à qual o Serviço MCP se refere.
• Para invocar um serviço MCP, são necessários EXECUTE no serviço MCP, USE CATALOG e USE SCHEMA em seu catálogo e esquema pai, além de atribuição ao espaço de trabalho em que você emite a solicitação.

Criar uma conexão

Um serviço MCP se refere a uma conexão HTTP do Unity Catalog que armazena com segurança o endpoint e as credenciais do servidor externo. Azure Databricks executa um proxy gerenciado na frente dele para lidar com a autenticação e a atualização de token, para que você não insira credenciais em seu agente ou código do cliente.

Crie a conexão no nível do esquema para que ela seja governada junto com o Serviço MCP. Você pode configurá-lo antecipadamente com as etapas abaixo ou criar uma enquanto cria o Serviço MCP clicando em Criar nova conexão. As conexões no nível do Metastore têm suporte, mas não são recomendadas.

Escolha uma das duas maneiras:

Criar uma conexão HTTP

Para qualquer servidor MCP, incluindo servidores auto-hospedados ou de terceiros:

1. Vá para Catálogo>Conexões>Criar conexão.
2. Selecione HTTP como o tipo de conexão.
3. Insira a URL do servidor MCP.
4. Escolha um tipo de autenticação: token de portador, OAuth M2M, OAuth U2M ou Registro dinâmico de cliente. Para obter detalhes de instalação, consulte Criar uma conexão com o serviço externo.

Para provedores OAuth gerenciados — Glean, GitHub, Atlassian e Slack — Azure Databricks gerencia as credenciais, para que você não registre seu próprio aplicativo OAuth. Consulte provedores OAuth gerenciados.

Instalar pelo Marketplace

Use um servidor MCP selecionado do Azure Databricks Marketplace com conexão pré-configurada. Consulte Obter acesso a servidores MCP externos.

Criar o serviço MCP

Você pode criar um serviço MCP da interface do usuário ou com a API REST. O Beta não dá suporte à DDL do SQL para serviços MCP.

interface do usuário

1. No seu workspace do Azure Databricks, vá para Gateway de IA>MCPs>Registrar servidor MCP ou vá para Catálogo, selecione um esquema e clique em Criar>Serviço MCP.
2. Insira o catálogo, o esquema e um nome para o Serviço MCP. O nome não pode ser alterado após a criação.
3. Selecione uma conexão HTTP existente com o servidor MCP ou clique em Criar uma conexão para criar uma. Navegue por um esquema para selecionar uma conexão no nível do esquema; para usar uma conexão no nível do metastore, desative Navegar por um esquema.
4. Em Ferramentas, selecione quais ferramentas disponibilizar. Consulte Selecionar quais ferramentas são expostas.
5. Opcionalmente, adicione um comentário que descreva o Serviço MCP.
6. Clique em Criar. O Serviço MCP é publicado no catálogo e no esquema que você especificou.

API REST

Crie um serviço MCP que faça referência a uma conexão HTTP existente do Catálogo do Unity. Defina parent para o esquema de destino e mcp_service_id para o nome do serviço:

databricks api post \
  "/api/2.1/unity-catalog/mcp-services?parent=schemas/main.default&mcp_service_id=my_mcp" \
  --json '{
    "comment": "External MCP server",
    "config": {
      "connection": {
        "name": "connections/main.default.my_connection"
      },
      "include_tool_selectors": []
    }
  }'

include_tool_selectors controla quais ferramentas o serviço expõe. Uma lista vazia expõe todas as ferramentas. Consulte Selecionar quais ferramentas são expostas.

Atualize um serviço MCP existente com uma PATCH solicitação e um update_mask que nomeia os campos a serem alterados:

databricks api patch \
  "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp?update_mask=comment" \
  --json '{ "comment": "Updated description" }'

Authenticate

Se o Serviço MCP fizer referência a uma conexão que usa o OAuth por usuário, conclua um logon único antes da primeira chamada:

1. Abra a página de detalhes do Serviço MCP no Gerenciador de Catálogos.
2. Clique em Logon e conclua o fluxo de consentimento OAuth do provedor.
3. Depois de entrar, a página de detalhes mostra automaticamente a lista de ferramentas descobertas.

O Unity Catalog armazena o token vinculado à sua identidade. Se você acessar o Serviço MCP antes de fazer login, o Gateway de IA retornará um erro solicitando que você se autentique.

Conceder acesso aos colegas de equipe

Por padrão, somente o proprietário do Serviço MCP pode invocá-lo. Conceda EXECUTE para permitir que outros usuários, grupos ou entidades de serviço invoquem o serviço. Uma única EXECUTE concessão abrange todas as ferramentas do serviço.

interface do usuário

1. Abra o serviço MCP no Catalog Explorer ou acesse AI Gateway>MCPs e selecione o serviço.
2. Acesse a guia Permissões.
3. Selecione Conceder.
4. Selecione os usuários, grupos ou entidades de serviço aos quais dar acesso.
5. Selecione o privilégio EXECUTE .
6. Selecione Conceder.

API REST

databricks api patch \
  "/api/2.1/unity-catalog/permissions/mcp_service/main.default.my_mcp" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["EXECUTE"] }
    ]
  }'

Invocar um serviço MCP

Experimente um serviço MCP no AI Playground, na linha de comando ou no código do seu agente ou cliente.

Testar o serviço MCP

Playground de IA

Teste as ferramentas de um serviço MCP na interface do usuário sem escrever código:

1. Vá para o AI Playground em seu workspace Azure Databricks.
2. Selecione um modelo com o rótulo Ferramentas ativadas.
3. Clique em Ferramentas > + Adicionar ferramenta e selecione Servidores MCP.
4. Selecione servidores MCP externos e selecione o Serviço MCP.
5. Converse com o modelo para ver como ele chama as ferramentas do Serviço MCP.

Você também pode testar no Genie Code – consulte Adicionar servidores MCP ao Assistente.

CURL

Para uma verificação rápida de linha de comando, use a solicitação gerada na página de detalhes do Serviço MCP. Em Introdução, clique em Gerar Token de Acesso para copiar um token de acesso nos exemplos de solicitação. Os exemplos passam o token como um token de portador no Authorization cabeçalho.

Você também pode autenticar a CLI do Databricks em seu workspace e, em seguida, usar databricks auth token para obter um token de acesso OAuth:

databricks auth login --host https://<workspace-url>

Todas as solicitações vão para o mesmo ponto de extremidade do Serviço MCP— o JSON-RPC method no corpo da solicitação seleciona a operação. Liste as ferramentas que o serviço expõe:

TOKEN=$(databricks auth token | jq -r .access_token)

curl -s -X POST \
  "https://<workspace-url>/ai-gateway/mcp-services/main.default.my_mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Acione uma ferramenta:

curl -s -X POST \
  "https://<workspace-url>/ai-gateway/mcp-services/main.default.my_mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"<tool_name>","arguments":{}}}'

Usar do código do agente ou de um agente de codificação

• Código do agente (SDK do OpenAI Agents, LangGraph ou Model Serving): consulte Usar servidores MCP em agentes.
• Assistentes de IA e agentes de codificação (Claude, Claude Code, Cursor): consulte Conectar MCPs a assistentes de IA e agentes de codificação.

Gerenciar um serviço MCP

Selecione quais ferramentas são expostas

Por padrão, um Serviço MCP disponibiliza todas as ferramentas que o servidor MCP fornece. Para disponibilizar apenas um subconjunto, selecione as ferramentas ao criar o Serviço MCP ou atualize a seleção mais tarde. Cada seletor é comparado com os nomes das ferramentas: um padrão que termina em * é uma correspondência por prefixo (get_* corresponde a get_me e get_issue), e qualquer outro valor é uma correspondência exata (search_repositories corresponde apenas a essa ferramenta).

interface do usuário

No fluxo de criação, em Ferramentas:

• Selecione Selecionar manualmente para selecionar cada ferramenta individualmente.
• Selecione Avançado para inserir padrões de seleção usando o prefixo e as regras de correspondência exata descritas acima.
• Ative Incluir automaticamente ferramentas adicionadas a este servidor no futuro para disponibilizar novas ferramentas conforme o servidor MCP as adiciona.

API REST

Para alterar a seleção da ferramenta após a criação, defina include_tool_selectors usando uma solicitação PATCH. Restrinja um serviço a somente get_* ferramentas:

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_*"]
    }
  }'

Redefina para disponibilizar todas as ferramentas, definindo include_tool_selectors como uma lista vazia.

As ferramentas que você não selecionar não aparecem em tools/list, e o serviço MCP rejeita uma tools/call para uma ferramenta não selecionada:

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

Aplicar uma política de serviço

Uma política de serviço avalia cada chamada de ferramenta antes de ser executada (ON CALL) e, opcionalmente, seu resultado (ON RESULT). Uma política pode permitir, negar, exigir aprovação humana ou transformar a solicitação, por exemplo, para bloquear operações destrutivas ou redigir a PII, sem alterar quais ferramentas estão disponíveis. As políticas de serviço fazem parte da governança de IA no Unity Catalog.

Para criar uma função de política e anexá-la a um serviço MCP, consulte Políticas de serviço para objetos protegíveis de IA e Criar e anexar uma política de serviço.

Definir limites de taxa

Limite a frequência com que os agentes podem chamar um Serviço MCP para controlar o custo e proteger o servidor externo. Consulte Configurar limites de taxa para serviços de IA usando o Gateway de IA do Unity.

Monitorar o uso

O Unity AI Gateway registra atividades de cada serviço MCP nas tabelas do sistema do Unity Catalog:

• Uso: volume de chamadas, erros e latência em system.ai_gateway.usage (filtro service_type = 'MCP_SERVICE'). Consulte Uso de modelos nos serviços do Unity AI Gateway.
• Auditoria: alterações no plano de controle (createMcpService, updateMcpService, deleteMcpService) e cada invocação (mcpCall) em system.access.audit. Confira Tabela de referência do sistema de logs de auditoria.
• Rastreamentos: solicitações de chamada de ferramentas, respostas e decisões de política são registradas no log de rastreamento, que é habilitado uma única vez no nível da conta e compartilhado entre todos os Serviços MCP.
• Painel: o tráfego do servidor MCP externo aparece no painel integrado de uso do Gateway de IA da Unity. Consulte o painel de uso interno.

Para ver todas as tabelas do sistema do Unity Catalog, consulte Referência das tabelas do sistema. Para obter uma visão geral da governança do tráfego de IA, consulte a governança de IA no Catálogo do Unity.

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.

Limitations

Durante o Beta, 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 

• Use servidores MCP em agentes para chamar um serviço MCP programaticamente a partir do código do agente.
• Conecte MCPs a assistentes de IA e agentes de codificação para conectar agentes de codificação e assistentes de IA.
• Governança de IA com o Unity AI Gateway para gerenciar servidores MCP e endpoints de LLM a partir de um local central.