Registro de um servidor MCP externo

info

Beta

Este recurso está em Beta. Administradores de conta podem controlar o acesso a este recurso na página Prévias do console da conta. Consulte Gerenciar prévias do Databricks.

Esta página descreve como registrar um servidor MCP auto-hospedado ou de terceiros como um Serviço MCP no Unity Catalog e, em seguida, invocá-lo do AI Playground, da linha de comando ou do código do seu agente. Registrar o servidor como um recurso protegível do Unity Catalog permite que o Unity AI Gateway faça proxy de cada chamada com credenciais gerenciadas, para que os agentes nunca manipulem os tokens do servidor. Para restringir quais ferramentas o serviço expõe e gerenciar chamadas individuais, consulte Gerenciar um serviço MCP.

Para uma ferramenta SaaS pronta para uso, sem servidor para hospedar, utilize um serviço MCP fornecido pelo Databricks em vez disso.

Requisitos

• Um workspace habilitado para o Unity Catalog.

• O Unity AI Gateway Beta e a prévia de Servidores MCP Gerenciados habilitada para sua account. Consulte Gerenciar prévias do Databricks.

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

Registro de um servidor MCP externo

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

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

O servidor MCP externo deve usar o mecanismo de transporte HTTP streaming. São necessárias as seguintes permissões:

• Para criar a conexão , CREATE CONNECTION no esquema onde a criar.
• Para criar um serviço MCP, USE CATALOG e USE SCHEMA no catálogo e esquema pai, CREATE SERVICE no esquema e USE CONNECTION na conexão que o serviço MCP referencia.
• Para invocar um serviço MCP, EXECUTE no serviço MCP, USE CATALOG e USE SCHEMA em seu catálogo e esquema pai, e atribuição ao workspace onde você emite a solicitação.

atenção

A invocação de um serviço MCP exige **nenhum privilégio na conexão subjacente** —EXECUTE no serviço MCP é suficiente. Não conceda USE CONNECTION aos usuários finais: isso permite que eles chamem o servidor externo diretamente pela conexão, ou façam o registro do seu próprio serviço MCP nele, ignorando a seleção de ferramentas, políticas de serviço e auditoria do seu serviço MCP. Reserve o acesso à conexão para autores de serviço e administradores.

Passo 1. Criar uma conexão

Um Serviço MCP faz referência a uma conexão HTTP do Unity Catalog que armazena com segurança o endpoint e as credenciais do servidor externo. O Databricks executa um proxy gerenciado à frente dele para lidar com a autenticação e o refresh de tokens, para que você não incorpore credenciais no seu agente ou código de cliente.

Crie a conexão no nível de esquema para que seja governada juntamente com o Serviço MCP. Você pode configurá-lo com antecedência com os passos abaixo, ou criar um enquanto você cria o Serviço MCP clicando em Criar nova conexão . As conexões em nível de metastore são suportadas, mas não recomendadas.

Escolha uma das duas maneiras:

Create an HTTP connection

Para qualquer servidor MCP, incluindo servidores próprios ou de terceiros:

1. Vá para Catálogo > Conexões > Criar conexão .
2. Selecione **HTTP** como o tipo de conexão.
3. Digite a URL do servidor MCP.
4. Escolha um tipo de autenticação: bearer token, OAuth M2M, OAuth U2M ou Dynamic Client Registration. Para obter detalhes de configuração, consulte Crie uma conexão com o serviço externo.

Para provedores de OAuth gerenciados—Glean, GitHub, Atlassian e Slack—o Databricks gerencia as credenciais, então você não registra seu próprio aplicativo OAuth. Consulte Provedores de OAuth gerenciados.

Install from Marketplace

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

Passo 2. Criar o serviço MCP

Você pode criar um Serviço MCP da IU ou com a API REST. O Beta não oferece suporte a SQL DDL para Serviços MCP.

UI

1. Em seu workspace Databricks, vá para AI Gateway > MCPs > Registro 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 para o servidor MCP, ou clique em **Criar nova conexão** para criar uma. Navegue sob um esquema para selecionar uma conexão em nível de esquema; para usar uma conexão em nível de metastore, desative **Navegar sob 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 esquema que o senhor especificou.

REST API

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

Bash

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 as ferramentas expostas.

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

Bash

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

Etapa 3. Autenticar

Se o Serviço MCP referencia uma conexão que usa OAuth por usuário, conclua um login único antes da primeira chamada:

1. Abra a página de detalhes do serviço MCP no Catalog Explorer.
2. Clique em Fazer login e conclua o fluxo de consentimento OAuth do provedor.
3. Após o login, a página de detalhes exibe automaticamente a lista de ferramentas descobertas.

O Unity Catalog armazena os tokens associados à sua identidade. Se você chamar o Serviço MCP antes de fazer login, o AI Gateway retornará um erro solicitando que você se autentique.

Passo 4. Conceder acesso aos colegas de equipe

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

UI

1. Abra o serviço MCP no Catalog Explorer, ou vá para AI Gateway > MCPs e selecione o serviço.
2. Vá para a Permissões tab.
3. Clique em Conceder .
4. Selecione os usuários, grupos ou entidades de serviço aos quais conceder acesso.
5. Selecione o privilégio de EXECUÇÃO .
6. Clique em Conceder .

REST API

Bash

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

O passo 5. Invocar um serviço MCP

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

Teste o serviço MCP

AI Playground

Teste as ferramentas de um serviço MCP na UI sem escrever código:

1. Acesse o AI Playground em seu workspace da 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, em seguida, selecione o Serviço MCP.
5. Converse com o modelo para ver como ele chama as ferramentas do Serviço MCP.

É possível também testar de Genie Code — consulte Adicionar servidores MCP ao Assistente.

CURL

Para uma verificação rápida por linha de comando, use a solicitação gerada na página de detalhes do Serviço MCP. Em **Começar**, clique em **Gerar Access Token** para copiar um access token para os exemplos de solicitação. Os exemplos passam o token como um bearer token no cabeçalho Authorization.

É possível também autenticar a CLI do Databricks em seu workspace e, em seguida, usar databricks auth token para obter um access token OAuth:

Bash

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

Todas as solicitações vão para o mesmo endpoint 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:

Bash

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":{}}'

Chamar uma ferramenta:

Bash

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":{'

Utilize a partir do código de agente ou de um agente de codificação

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

Próximos os passos

• Governe um serviço MCP para restringir quais ferramentas o serviço expõe e aplique políticas de serviço.
• Conecte agentes a ferramentas de terceiros com os Serviços MCP para uma visão geral dos Serviços MCP e dos serviços fornecidos pela Databricks.
• Governança de AI com o Unity AI Gateway para governar servidores MCP e endpoints de LLM de um local central.