Chamar ferramentas MCP de um agente Python

Use ferramentas MCP em um agente Python personalizado criado com LangGraph, o OpenAI Agents SDK ou o cliente OpenAI. Os exemplos mostram como fazer login, descobrir ferramentas e executar um agente localmente com suas próprias credenciais do Databricks.

Para um aplicativo que chama ferramentas em nome de usuários conectados, consulte Conecte seu aplicativo às ferramentas MCP.

Para outras formas de conexão, consulte Agentes de codificação compatíveis, Outros clientes MCP ou Adicionar ferramentas MCP com a CLI do Agent Bricks.

Pré-requisitos

• Python 3.12 em seu computador.
• A URL de um MCP fornecido pelo Databricks, um MCP registrado ou um servidor no Databricks Apps. Se alguém compartilhou um MCP com você, essa pessoa deve conceder acesso a você. Conclua o login do provedor se ele usar OAuth por usuário. Para um servidor no Databricks Apps, você precisa de CAN USE no aplicativo.
• Acesso a um endpoint de modelo que ofereça suporte à chamada de ferramentas do Databricks. O exemplo usa databricks-claude-sonnet-4-5. Substitua-o por um endpoint disponível em seu workspace.

Para usar system.ai.dbsql, system.ai.sandbox ou system.ai.web_search, um administrador de account deve habilitar a versão beta do Unity Gateway na página Previews do console da account. Consulte Gerenciar prévias da account.

Para opções de identidade, consulte Autenticação de saída compatível. Para requisitos de conectividade, consulte Rede MCP.

o passo 1: Instalar e entrar

1. Se você ainda não instalou a CLI do Databricks, execute este comando no macOS ou Linux:

   Bash

   curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sh

   Para o Windows ou outros métodos de instalação, consulte Instalar a CLI do Databricks.

2. Faça login no seu Workspace:

   Bash

   databricks auth login --host https://<workspace-hostname> --profile DEFAULT

3. Instale as bibliotecas do Python:

   Bash

   pip install --upgrade databricks-mcp databricks-sdk "mcp>=1.24,<2"

Os exemplos usam o MCP Python 1.x, que é compatível com os frameworks de agentes abaixo.

O passo 2: Conectar ao seu servidor

Salve o seguinte código como mcp_agent.py. Substitua <mcp-server-url> pela URL do seu servidor:

• MCP fornecido ou registrado pela Databricks: https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>.
• Servidor no Databricks Apps: copie o URL do aplicativo em sua página de visão geral e adicione /mcp.

Python

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient

workspace_client = WorkspaceClient()
server_url = "<mcp-server-url>"
mcp_client = DatabricksMCPClient(
    server_url=server_url,
    workspace_client=workspace_client,
)

tools = mcp_client.list_tools()
for tool in tools:
    print(tool.name, tool.description, tool.inputSchema, sep="\n")

Faça a execução do script:

Bash

python mcp_agent.py

Você deve ver as ferramentas do seu servidor, com descrições e esquemas de entrada. Escolha uma tarefa de somente leitura que uma dessas ferramentas suporta para o próximo o passo. Se a lista estiver vazia ou a conexão falhar, consulte Autenticação MCP.

Use outro servidor

• Para um MCP integrada, use seu nome completo no URL do MCP, como system.ai.github.
• Para uma integração existente com um servidor MCP de workspace, substitua server_url pela URL de endpoint desse workspace.

Para encontrar MCPs que você pode acessar em um catálogo e esquema, execução:

Bash

databricks ai-gateway list-mcp-services --parent schemas/system.ai

Substitua system.ai pelo seu <catalog>.<schema> para listar os MCPs registrados. A CLI lida com a paginação.

O passo 3: Execução um agente com essas ferramentas

Escolha sua estrutura, instale o pacote e adicione seu exemplo em Python a mcp_agent.py. Cada exemplo usa o mesmo server_url e o logon do workspace do o passo 2.

LangGraph

O exemplo converte blocos de conteúdo MCP para o formato de mensagem de chat do modelo com convert_to_openai_messages.

Bash

pip install --upgrade databricks-langchain langgraph

Python

import asyncio
from databricks_langchain import (
    ChatDatabricks,
    DatabricksMCPServer,
    DatabricksMultiServerMCPClient,
)
from langchain_core.messages import convert_to_openai_messages
from langgraph.prebuilt import create_react_agent

async def main():
    client = DatabricksMultiServerMCPClient([
        DatabricksMCPServer(
            name="my-mcp-server",
            url=server_url,
            workspace_client=workspace_client,
        ),
    ])
    agent = create_react_agent(
        ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
        tools=await client.get_tools(),
        prompt=lambda state: convert_to_openai_messages(state["messages"]),
    )
    task = input("Ask the agent to use a tool: ")
    result = await agent.ainvoke({
        "messages": [{"role": "user", "content": task}],
    })
    for message in result["messages"]:
        print(message)

asyncio.run(main())

Notebook de implantação (opcional)

Para implantação de Model Serving, adapte este notebook para usar a URL do seu servidor:

LangGraph MCP tool-calling agent

Abrir notebook em uma nova abaOpen in Databricks

OpenAI Agents SDK

Bash

pip install --upgrade databricks-openai openai-agents

Python

import asyncio
from agents import Agent, Runner, set_default_openai_api, set_default_openai_client
from agents.mcp import MCPServerStreamableHttpParams
from agents.tracing import set_trace_processors
from databricks_openai import AsyncDatabricksOpenAI
from databricks_openai.agents.mcp_server import McpServer

set_default_openai_client(AsyncDatabricksOpenAI())
set_default_openai_api("chat_completions")
set_trace_processors([])

async def main():
    async with McpServer(
        name="my-mcp-server",
        params=MCPServerStreamableHttpParams(url=server_url),
        workspace_client=workspace_client,
    ) as server:
        agent = Agent(
            name="Tool-using agent",
            instructions="Use the available tools to answer the user's question.",
            model="databricks-claude-sonnet-4-5",
            mcp_servers=[server],
        )
        task = input("Ask the agent to use a tool: ")
        result = await Runner.run(agent, task)
        for item in result.new_items:
            print(item.to_input_item())

asyncio.run(main())

Notebook de implantação (opcional)

Para implantação de Model Serving, adapte este notebook para usar a URL do seu servidor:

Agents SDK MCP tool-calling agent

Abrir notebook em uma nova abaOpen in Databricks

OpenAI client

Bash

pip install --upgrade databricks-openai

Este exemplo execução o loop de chamada de ferramenta explicitamente usando o cliente compatível com OpenAI.

Python

import json
from databricks_openai import DatabricksOpenAI, McpServerToolkit

toolkit = McpServerToolkit(url=server_url, workspace_client=workspace_client)
tools_by_name = {tool.name: tool for tool in toolkit.get_tools()}
model_client = DatabricksOpenAI()
messages = [{"role": "user", "content": input("Ask the agent to use a tool: ")}]

for _ in range(10):
    response = model_client.chat.completions.create(
        model="databricks-claude-sonnet-4-5",
        messages=messages,
        tools=[tool.spec for tool in tools_by_name.values()],
    )
    message = response.choices[0].message
    messages.append(message.model_dump(exclude_none=True))
    if not message.tool_calls:
        print(message.content)
        break
    for call in message.tool_calls:
        try:
            tool = tools_by_name.get(call.function.name)
            if tool is None:
                raise ValueError(f"Unknown tool: {call.function.name}")
            arguments = json.loads(call.function.arguments or "{}")
            if not isinstance(arguments, dict):
                raise ValueError("Tool arguments must be a JSON object.")
            output = tool.execute(**arguments)
        except Exception as error:
            output = json.dumps({"error": str(error)})
        print(call.function.name, output)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": str(output),
        })
else:
    raise RuntimeError("The agent reached the tool-calling limit.")

Notebook de implantação (opcional)

Para implantação de Model Serving, adapte este notebook para usar a URL do seu servidor:

OpenAI MCP tool-calling agent

Abrir notebook em uma nova abaOpen in Databricks

Execute python mcp_agent.py novamente. Quando solicitado, peça a tarefa somente leitura que você escolheu, incluindo quaisquer entradas necessárias. Por exemplo, se o seu servidor tiver uma ferramenta de busca de tickets, peça a ela para localizar tickets abertos em um projeto específico.

Verifique a conversa impressa para ver uma chamada de ferramenta, seu resultado e a resposta do agente. Uma resposta sem uma chamada de ferramenta não confirma que o servidor MCP foi usado.

Chamar uma ferramenta diretamente para solucionar problemas

Execute-o após o código de conexão no o passo 2: Faça a execução após o código de conexão do passo 2:

Python

import json

tool_name = input("Read-only tool name: ")
arguments = json.loads(input("Tool arguments as a JSON object: "))
result = mcp_client.call_tool(tool_name, arguments)
print(result)

Verifique se o resultado não apresenta erro de ferramenta e contém os dados esperados.

Descubra nomes de ferramentas e esquemas de entrada com list_tools() antes de chamar uma ferramenta. Os formatos de resultado variam de acordo com a ferramenta:

• Se structuredContent estiver presente, use esse resultado estruturado diretamente. Uma ferramenta pode descrever sua forma com outputSchema.
• Caso contrário, inspecione os blocos content. Analise um bloco de texto como JSON somente se a ferramenta retornar JSON. O MCP também oferece suporte a texto simples e outros tipos de conteúdo.
• Verifique isError e inspecione uma resposta de amostra antes de depender de campos de saída específicos.

Implante e compartilhe quando estiver tudo pronto

O exemplo local execução como você. Quando você implantar o agente no Databricks Apps, escolha a identidade que ele usa: o Service Principal do aplicativo para acesso compartilhado ou o usuário solicitante para acesso por usuário.

Para MCPs fornecidos ou registrados pela Databricks:

• Conceda ao chamador acesso ao MCP e ao catálogo e esquema pai dele.
• Configure o acesso por usuário se o seu agente agir em nome de um usuário. Se seu aplicativo conecta usuários com seu próprio provedor de identidade, consulte Conecte seu aplicativo às ferramentas MCP.
• Govern the MCP to restrict tools, apply policies, set rate limits, and monitor calls.

Para Endpoint de MCP de Workspace ou servidores hospedados em Databricks Apps, conceda acesso aos recursos subjacentes ou ao app. Consulte Autenticação de agente.

Outros recursos

• Implante um agente no Model Serving.
• Configure a autenticação para agentes de Model Serving.