Usar servidores MCP externos em agentes

Importante

Esse recurso está em Visualização Pública.

Depois de instalar um servidor MCP externo em seu workspace, use-o no código do agente conectando-se à URL de proxy gerenciada por Azure Databricks. O proxy faz com que os servidores externos se comportem como servidores MCP gerenciados, tratando a autenticação e o gerenciamento de tokens.

Para instalar um servidor MCP externo, consulte Instalar um servidor MCP externo.

Conectar-se a um servidor MCP externo

O padrão da URL do proxy é https://<workspace-hostname>/api/2.0/mcp/external/<connection-name>, em que <connection-name> é a conexão do Unity Catalog que você registrou para o serviço externo.

Escolha a guia que corresponde à estrutura do agente e ao destino de implantação:

SDK de Agentes do OpenAI (Aplicativos)

from agents import Agent, Runner
from databricks.sdk import WorkspaceClient
from databricks_openai.agents import McpServer

workspace_client = WorkspaceClient()
host = workspace_client.config.host

async with McpServer(
    url=f"{host}/api/2.0/mcp/external/<connection-name>",
    name="external-service",
    workspace_client=workspace_client,
) as external_server:
    agent = Agent(
        name="Connected agent",
        instructions="You are a helpful assistant with access to external services.",
        model="databricks-claude-sonnet-4-5",
        mcp_servers=[external_server],
    )
    result = await Runner.run(agent, "Send a Slack message to the team about the deployment")
    print(result.final_output)

Conceda ao aplicativo acesso à conexão com o Unity Catalog em databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_connection'
          uc_securable:
            securable_full_name: '<connection-name>'
            securable_type: 'CONNECTION'
            permission: 'USE_CONNECTION'

LangGraph (Aplicativos)

from databricks.sdk import WorkspaceClient
from databricks_langchain import ChatDatabricks, DatabricksMCPServer, DatabricksMultiServerMCPClient
from langgraph.prebuilt import create_react_agent

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMultiServerMCPClient([
    DatabricksMCPServer(
        name="external-service",
        url=f"{host}/api/2.0/mcp/external/<connection-name>",
        workspace_client=workspace_client,
    ),
])

async with mcp_client:
    tools = await mcp_client.get_tools()
    agent = create_react_agent(
        ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
        tools=tools,
    )
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Send a Slack message to the team about the deployment"}]}
    )
    print(result["messages"][-1].content)

Conceda ao aplicativo acesso à conexão com o Unity Catalog em databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_connection'
          uc_securable:
            securable_full_name: '<connection-name>'
            securable_type: 'CONNECTION'
            permission: 'USE_CONNECTION'

Serviço de Modelo

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient
import mlflow

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/external/<connection-name>",
    workspace_client=workspace_client,
)

tools = mcp_client.list_tools()

mlflow.pyfunc.log_model(
    "agent",
    python_model=my_agent,
    resources=mcp_client.get_databricks_resources(),
)

Para implantar o agente, consulte Implantar um agente para aplicativos de IA generativos (Model Serving). Para obter detalhes sobre agentes de log com recursos mcp, consulte Usar servidores MCP gerenciados pelo Databricks.

Nível inferior: use o SDK do MCP diretamente

Se você não estiver usando um auxiliar de estrutura fornecido pelo Databricks, chame a URL do proxy com o SDK do MCP padrão. Esse padrão é independente da estrutura – use-o para orquestração personalizada ou quando precisar de controle direto sobre a sessão.

%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 mcp.client.streamable_http import streamablehttp_client as connect
from mcp import ClientSession


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

    async with connect(app_url, auth=DatabricksOAuthClientProvider(client)) as (
        read_stream,
        write_stream,
        _,
    ):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            response = await session.call_tool(name="<tool-name>", arguments={...})
            print(response.content[0].text)

await main()

Para uma alternativa síncrona, use DatabricksMCPClient diretamente:

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/external/<connection-name>",
    workspace_client=workspace_client,
)

tools = mcp_client.list_tools()
response = mcp_client.call_tool("<tool-name>", {...})
print(response.content[0].text)

Notebooks de exemplo: construir um agente com servidores MCP do Databricks

Os notebooks a seguir mostram como desenvolver agentes LangGraph e OpenAI que chamam ferramentas MCP, incluindo servidores MCP externos acessados por meio de endpoints de proxy do Databricks.

Agente de invocação de ferramentas LANGGraph MCP

Obter laptop

Agente de chamamentos de ferramentas do OpenAI MCP