Pular para o conteúdo principal

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 e trabalho compatíveis, Outros clientes MCP ou Adicionar ferramentas MCP com a CLI do Agent Bricks.

Pré-requisitos​

system.ai.dbsql, system.ai.sandbox e system.ai.web_search estão em Beta. Para usá-los, um administrador account deve habilitar a prévia do Enhanced Unity Gateway a partir da página Previews do console da account. O Unity Gateway em si está em disponibilidade geral. 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.
  • Endpoint MCP do workspace: https://<workspace-hostname> seguido por um desses caminhos:
    • Funções do Unity Catalog: /api/2.0/mcp/functions/{catalog}/{schema}/{function_name}
    • Pesquisa de AI: /api/2.0/mcp/ai-search/{catalog}/{schema}/{index_name}
    • Genie Agent: /api/2.0/mcp/genie/{genie_space_id}
    • Databricks SQL: /api/2.0/mcp/sql
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 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.

O exemplo usa um middleware de modelo que 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==0.22.0" "langgraph==1.2.20" "mcp>=1.24,<2"
Python
import asyncio
from databricks_langchain import (
ChatDatabricks,
DatabricksMCPServer,
DatabricksMultiServerMCPClient,
)
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call
from langchain_core.messages import convert_to_messages, convert_to_openai_messages

@wrap_model_call
async def convert_mcp_content(request, handler):
messages = convert_to_messages(convert_to_openai_messages(request.messages))
return await handler(request.override(messages=messages))

async def main():
client = DatabricksMultiServerMCPClient([
DatabricksMCPServer(
name="my-mcp-server",
url=server_url,
workspace_client=workspace_client,
),
])
agent = create_agent(
model=ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
tools=await client.get_tools(),
middleware=[convert_mcp_content],
)
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

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:

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​