Usar servidores MCP externos

Conecte o Databricks a servidores MCP (Model Context Protocol) externos para dar aos seus agentes acesso a uma ampla gama de ferramentas hospedadas fora do Databricks. Servidores MCP externos são servidores MCP de terceiros hospedados fora do Databricks aos quais você se conecta por meio de proxies gerenciados pelo Databricks.

Autenticação e segurança

O Databricks usa proxies MCP gerenciados e conexões HTTP do Unity Catalog para lidar com a autenticação com segurança em seu espaço de trabalho:

• Gerenciamento seguro de tokens: o Databricks lida com todos os fluxos OAuth e atualização de token automaticamente
• Sem credenciais expostas: os tokens nunca são expostos aos usuários finais
• Autenticação centralizada: padrões de autenticação consistentes usando conexões do Unity Catalog

Requerimentos

• Um espaço de trabalho com a visualização de Servidores MCP Gerenciados habilitada. Consulte Gerenciar visualizações do Azure Databricks.
• Você deve ter CREATE CONNECTION privilégio no metastore do Unity Catalog que armazena as informações de conexão MCP.
• O servidor MCP deve usar o mecanismo de transporte HTTP Streamable

Instalar um servidor MCP externo

Tem três opções para instalar servidores MCP externos para usar com os seus agentes. Todos os métodos criam uma ligação Unity Catalog que permite acesso seguro e autenticado ao servidor MCP.

Escolha o método de instalação com base no seu servidor MCP:

Do Marketplace da Databricks

Instale servidores MCP selecionados e pré-configurados diretamente do Azure Databricks Marketplace:

1. No seu espaço de trabalho do Azure Databricks, vá para a aba Marketplace>Agentes>Servidores MCP.

2. Localize o servidor MCP que deseja instalar e clique em Instalar.

3. Na caixa de diálogo de instalação, configure a conexão:

   • Nome da conexão: insira um nome para a conexão do Catálogo Unity (por exemplo, github_connection).
   • Host: O domínio host está pré-configurado para servidores selecionados.
   • Caminho base: O caminho base é pré-preenchido para servidores configurados.

   Credenciais: insira suas credenciais de autenticação. Os campos obrigatórios dependem do tipo de credencial do servidor:

   • Para autenticação de token de portador : Forneça seu token de portador.
   • Para a autenticação OAuth U2M: forneça o seu ID de cliente e chave secreta do cliente.

   Consulte a documentação do provedor do servidor MCP para obter instruções sobre como obter essas credenciais.

4. Clique em Instalar para criar a conexão.

Para obter detalhes completos sobre a instalação do Marketplace, consulte Obter acesso a servidores MCP externos.

Conexão HTTP personalizada

Crie uma conexão HTTP do Unity Catalog para instalar qualquer servidor MCP, incluindo servidores auto-hospedados ou de terceiros não disponíveis no Marketplace.

1. Crie uma conexão HTTP. Consulte Conexão HTTP.

2. Ao criar a conexão HTTP, marque a caixa de seleção É conexão mcp para habilitar a funcionalidade MCP.

3. Verifique se a URL de conexão aponta para um ponto de extremidade de servidor MCP válido.

Registo Dinâmico de Clientes (Experimental)

Use o Registo Dinâmico de Clientes (DCR) para registar e instalar automaticamente servidores MCP que suportam OAuth 2.0 DCR (RFC7591).

O DCR gere automaticamente a descoberta OAuth, o registo do cliente e a criação de ligações ao Catálogo Unity sem necessidade de configuração manual de credenciais.

Para utilizar o DCR, deve cumprir os seguintes requisitos:

• O servidor MCP deve suportar autorização DCR e OAuth 2.0.
• O servidor MCP deve expor os endpoints de metadados OAuth.

1. Instale ou atualize o databricks-mcp pacote para obter a versão mais recente:

   %pip install -U databricks-mcp
   %restart_python
   

2. Use a função de registo DCR para criar uma ligação ao Unity Catalog:

   from databricks.sdk import WorkspaceClient
   from databricks_mcp import register_mcp_server_via_dcr
   
   # Initialize workspace client
   workspace_client = WorkspaceClient()
   
   # Register MCP server via DCR
   connection_url = register_mcp_server_via_dcr(
       connection_name="my_mcp_server",
       mcp_url="https://mcp.example.com/api",
       workspace_client=workspace_client
   )
   
   print(f"Connection created: {connection_url}")
   

Após completar qualquer método de instalação:

• Uma ligação do Catálogo Unity é criada com os detalhes do seu servidor MCP

• O Azure Databricks provisiona um ponto de extremidade de proxy gerido que lida com segurança com autenticação e gestão de tokens.

• O servidor MCP está disponível no AI Playground e pode ser usado programaticamente em seus agentes

• Você pode conceder a outros usuários acesso à conexão por meio de permissões do Catálogo Unity

• O URL do endpoint do proxy segue este formato:

  https://<workspace-hostname>/api/2.0/mcp/external/{connection_name}
  

Para exibir seu servidor MCP, vá para seu espaço de trabalho >Agentes>MCP Servers

Compartilhar a conexão do servidor MCP

Conceda USE CONNECTION privilégios a entidades de identidade que precisam usar a conexão do servidor MCP:

1. No seu espaço de trabalho, vá para Catálogo>Conexões> As suas > de conexão.
2. Conceda às identidades acesso apropriado à conexão do Catálogo Unity.

Teste servidores MCP com o AI Playground

Teste servidores MCP diretamente no AI Playground sem escrever nenhum código:

1. Vá para AI Playground em seu espaço de trabalho Databricks.

2. Escolha um modelo com a etiqueta Ferramentas ativadas .

3. Clique em Ferramentas > + Adicionar ferramenta e selecione Servidores MCP nas opções de ferramenta disponíveis.

4. Na seção Servidores MCP , selecione Servidores MCP externos para procurar conexões disponíveis.

5. Escolha a conexão do Catálogo Unity instalada anteriormente (por exemplo, github_connection).

6. Converse com o LLM para testar como ele interage com suas ferramentas de servidor MCP. O AI Playground descobre automaticamente as ferramentas disponíveis do seu servidor MCP e as disponibiliza para o LLM.

Isso permite que você prototipe e teste rapidamente integrações de servidor MCP antes de criar agentes completos ou implantar na produção.

Usar servidores MCP programaticamente

Depois de instalar um servidor MCP, use-o programaticamente no código do agente conectando-se à URL do proxy. O proxy Databricks faz com que os servidores externos se comportem como servidores MCP gerenciados, manipulando autenticação e gerenciamento de tokens.

Cliente Databricks MCP

A abordagem recomendada trata os servidores MCP externos como servidores geridos pelo Databricks, adicionando o ponto de extremidade proxy à sua MANAGED_MCP_SERVER_URLS lista.

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient

# Initialize workspace client
workspace_client = WorkspaceClient()
host = workspace_client.config.host

# External MCP servers are proxied as managed servers, allowing you
# to use the same API for both managed and external servers
MANAGED_MCP_SERVER_URLS = [
    f"{host}/api/2.0/mcp/functions/system/ai",  # Default managed MCP
    f"{host}/api/2.0/mcp/external/github_connection"  # External MCP proxy
]

Para usar o servidor MCP em um agente, passe a URL do proxy para o managed_server_urls parâmetro:

# Use with agents - external servers work just like managed ones
import asyncio
from your_agent_code import create_mcp_tools  # Your agent's tool creation function

# Create tools from both managed and external (proxied) servers
mcp_tools = asyncio.run(
    create_mcp_tools(
        ws=workspace_client,
        managed_server_urls=MANAGED_MCP_SERVER_URLS
    )
)

Você também pode chamar a ferramenta diretamente usando o Databricks MCP Client:

# Direct tool call using DatabricksMCPClient
mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/external/github_connection",
    workspace_client=workspace_client
)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {[tool.name for tool in tools]}")

# Call a tool
response = mcp_client.call_tool(
    "list_commits",
    {"owner": "mlflow", "repo": "mlflow", "sha": "master"}
)
print(response.content[0].text)

SDK MCP padrão

Conecte-se a servidores MCP usando o SDK MCP padrão com async/await:

%pip install -U databricks-sdk databricks_mcp tabulate databricks_ai_bridge
%restart_python

import json
from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksOAuthClientProvider
from databricks.sdk.credentials_provider import ModelServingUserCredentials
from mcp.client.streamable_http import streamablehttp_client as connect
from mcp import ClientSession
from tabulate import tabulate


async def main():
    app_url = "https://<workspace-hostname>/api/2.0/mcp/external/github_connection"
    client = WorkspaceClient()

    async with connect(app_url, auth=DatabricksOAuthClientProvider(client)) as (
        read_stream,
        write_stream,
        _,
    ):
        async with ClientSession(read_stream, write_stream) as session:
            init = await session.initialize()
            print(json.dumps(init.model_dump(), indent=2))
            tools = await session.list_tools()
            print(json.dumps(tools.model_dump(), indent=2))

            arguments = {
                "owner": "mlflow",
                "repo": "mlflow",
                "sha": "master"
            }
            response = await session.call_tool(name="list_commits", arguments=arguments)

            data = json.loads(response.content[0].text)
            rows = []
            for commit in data:
                author = commit.get("commit", {}).get("author", {}).get("name")
                message = commit.get("commit", {}).get("message", "").split("\n")[0]
                html_url = commit.get("html_url", "")
                rows.append([author, message, html_url])

            # Print as table
            print(tabulate(rows, headers=["Author", "Message", "Commit URL"], tablefmt="github"))

await main()

Exemplos de blocos de anotações: Criar um agente com servidores Databricks MCP

Os blocos de anotações a seguir mostram como criar agentes LangGraph e OpenAI que chamam ferramentas MCP, incluindo servidores MCP externos acessados por meio de pontos de extremidade de proxy Databricks.

Agente de invocação de ferramentas LangGraph MCP

Obter caderno

Agente de chamada de ferramentas OpenAI MCP

Obter caderno

Limitações

• Não há suporte para conectividade privada com recursos em sua VPC usando Private Link. Entre em contato com sua equipe de suporte se precisar dessa funcionalidade.

• O Databricks suporta apenas servidores MCP externos que usam o mecanismo de transporte HTTP Streamable.

Próximos passos

• Usar servidores MCP gerenciados ao lado de servidores externos
• Conecte clientes a servidores MCP para acessar a infraestrutura Databricks MCP
• Crie servidores MCP personalizados para as necessidades da sua organização
• Implantar agentes que usam servidores MCP externos

• Use servidores MCP externos com Agent Bricks: Multi-Agent Supervisor.