Usa gli strumenti MCP in un agente Python

Connettiti a un server MCP, scopri i suoi strumenti ed esegui un agente Python che li utilizza. Usa l'URL di un MCP fornito da Databricks, del tuo MCP registrato o del tuo server sulle app Databricks.

Per utilizzare MCP da Claude Code, Codex o un altro agente di codifica, scegli il tuo client in Agenti di codifica supportati. Per altri assistenti e clienti MCP, vedi Altri clienti MCP.

Per un progetto CLI Agent Bricks, aggiungi strumenti MCP con la CLI. Gli esempi qui sotto mostrano come connettersi dal proprio codice Python.

Prerequisiti

• Python 3.12 sul tuo computer.
• L'URL MCP del tuo server. Se qualcuno ha condiviso un MCP con te, deve concederti l'accesso. Completa il login provider se utilizza OAuth per utente. Per un server in Databricks Apps, devi disporre di CAN USE per l'app.
• Accesso a un endpoint modello Azure Databricks che supporta la chiamata di uno strumento. L'esempio utilizza databricks-claude-sonnet-4-5. Sostituiscilo con un endpoint disponibile nel tuo spazio di lavoro.

Per utilizzare system.ai.dbsql, system.ai.sandbox, o system.ai.web_search, un amministratore dell'account deve abilitare la beta Unity Gateway dalla pagina delle anteprime della console account. Vedi Gestisci anteprime dell'account.

Per le scelte di identità e i requisiti di connettività, vedi Autenticazione e accesso alla rete.

Passo 1: Installa e accedi

1. Se non hai installato la CLI Databricks, esegui questo comando su macOS o Linux:

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

   Per Windows o altri metodi di installazione, vedi Installa la Databricks CLI.

2. Accedi al tuo spazio di lavoro:

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

3. Installa le librerie Python:

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

Gli esempi utilizzano MCP Python 1.x, compatibile con i framework agenti qui sotto.

Passo 2: Connettiti al tuo server

Salvare il codice seguente come mcp_agent.py. Sostituisci <mcp-server-url> con l'URL del tuo server:

• MCP fornito o registrato da Databricks:https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>.
• Server su Databricks Apps: Copia l'URL dell'app dalla sua pagina panoramica e aggiungi /mcp.

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")

Eseguire lo script:

python mcp_agent.py

Dovresti vedere gli strumenti del tuo server, con descrizioni e schemi di input. Scegli un compito di sola lettura che uno di questi strumenti supporti per il passo successivo. Se la lista è vuota o la connessione fallisce, vedi autenticazione MCP e networking.

Usa un altro server

• Per un MCP integrato, usa il suo nome completo nell'URL MCP, come system.ai.github.
• Per un'integrazione esistente con un server MCP di workspace legacy, sostituisci server_url con l'URL dell'endpoint legacy.

Per trovare MCP accessibili in un catalogo e schema, esegui:

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

Sostituisci system.ai con <catalog>.<schema> per elencare gli MCP registrati. La CLI gestisce la paginazione.

Passo 3: Esegui un agente con questi strumenti

Scegli il tuo framework, installa il suo pacchetto e aggiungi il suo esempio in Python a mcp_agent.py. Ogni esempio utilizza lo stesso server_url e lo stesso accesso allo spazio di lavoro del passaggio 2.

LangGraph

L'esempio converte i blocchi di contenuto MCP nel formato di messaggio chat del modello con convert_to_openai_messages.

pip install --upgrade databricks-langchain langgraph

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())

OpenAI Agents SDK

pip install --upgrade databricks-openai openai-agents

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())

Client OpenAI

pip install --upgrade databricks-openai

Questo esempio esegue esplicitamente il ciclo di chiamata dello strumento usando il client compatibile con OpenAI.

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.")

Eseguire python mcp_agent.py di nuovo. Quando ti viene chiesto, richiedi l’attività in sola lettura che hai scelto, includendo eventuali dati richiesti. Ad esempio, se il tuo server ha uno strumento di ricerca ticket, chiedigli di trovare ticket aperti in un progetto specifico.

Controlla la conversazione stampata per una chiamata a uno strumento, il risultato e la risposta dell'agente. Una risposta senza una chiamata allo strumento non conferma che il server MCP sia stato utilizzato.

Invoca direttamente uno strumento per la risoluzione dei problemi

Usa il nome dello strumento e lo schema di input stampati nel passo 2. Questo esempio richiede il nome e gli argomenti per funzionare con gli strumenti del tuo server. Eseguilo dopo il codice per la connessione nel passaggio 2:

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)

Controlla che il risultato non abbia errori di strumento e contenga i dati che ti aspettavi.

Scopri i nomi degli strumenti e gli schemi di input list_tools() prima di chiamare uno strumento. I formati dei risultati variano a seconda dello strumento:

• Se structuredContent è presente, usa direttamente quel risultato strutturato. Uno strumento può descrivere la sua forma con outputSchema.
• Altrimenti, ispeziona i content blocchi. Analizza un blocco di testo come JSON solo se lo strumento restituisce JSON. MCP supporta anche il testo semplice e altri tipi di contenuto.
• Controlla isError e ispeziona una risposta campione prima di affidarti a campi di output particolari.

Distribuisci e condividi quando sei pronto

L'esempio locale viene eseguito con i tuoi privilegi. Quando implementi l'agente in Databricks Apps, scegli l'identità che utilizza: il service principal dell'app per l'accesso condiviso, oppure l'utente chiamante per l'accesso per ogni utente.

Per i MCP forniti o registrati da Databricks:

• Concedi al chiamante l'accesso all'MCP e al suo catalogo e schema padre.
• Configura l'accesso per utente se il tuo agente agisce per conto di un utente.
• Governa l'MCP per limitare gli strumenti, applicare politiche, impostare limiti di frequenza e monitorare le chiamate.

Per server di workspace legacy o server ospitati su Databricks Apps, concedere l'accesso alle risorse sottostanti o all'app sottostante. Vedi Autenticazione dell'agente.

Risorse aggiuntive

• Distribuisci un agente su Model Serving.
• Configura l'autenticazione per gli agenti Model Serving.