Conecte seu aplicativo às ferramentas MCP

Crie seu próprio aplicativo usando servidores MCP (Model Context Protocol), incluindo os MCPs no esquema system.ai e MCPs cujo registro é feito por você. Seu aplicativo chama ferramentas como o usuário conectado. A governança do Unity Gateway controla quais MCPs e ferramentas cada usuário pode chamar.

Use autorização de usuário quando seu aplicativo estiver em execução no Databricks Apps. Se seu aplicativo registrar usuários com um provedor de identidade externo, use a federação de tokens OAuth para obter um token do Databricks. Este guia abrange aplicativos que atendem a vários usuários. Para criar e testar um agente localmente com suas próprias credenciais, consulte Chamar ferramentas MCP de um agente Python.

Para MCPs que usam OAuth por usuário, os usuários também autorizam sua account de provedor externa. Os passos seguintes abrangem a obtenção do token do Databricks e a conclusão do início de sessão do provedor.

Configurar autenticação e acesso

Antes de adicionar código, dê aos usuários acesso aos MCPs e configure a autenticação do seu aplicativo.

Dar acesso aos usuários ao MCPs

Estes requisitos aplicam-se aos dois métodos de autenticação:

• Adicione cada usuário ao workspace do Databricks. O acesso do consumidor é suficiente para chamar MCPs através do Unity Gateway.
• Conceda a cada usuário EXECUTE nos MCPs, além de USE CATALOG e USE SCHEMA em seu catálogo e esquema pai. Consulte Compartilhar um MCP.

Configurar a autenticação do seu aplicativo

Escolha a opção que corresponde ao seu aplicativo:

Databricks Apps

1. Habilite autorização de usuário para o aplicativo. Seu aplicativo usa o token de usuário do Databricks encaminhado diretamente, sem troca de token ou uma política de federação de account.
2. Adicione os escopos de autorização do usuário: ai-gateway para chamadas de ferramentas e unity-catalog para APIs de status de descoberta e entrada.
3. Conceda a cada usuário CAN USE no aplicativo.

External identity provider

Se seu aplicativo já tem um token OAuth do Databricks para o usuário, use-o diretamente e pule a configuração de federação e a troca de token. O token precisa dos escopos ai-gateway e unity-catalog para as APIs neste guia. Caso contrário, conclua estes os passos:

1. Solicite a um administrador account que configure uma política de federação de account para seu provedor de identidade. A política define o emissor, o público e o mapeamento de usuário aceitos.
2. Obtenha um token para o usuário logado de seu provedor de identidade. O primeiro o passo de código o troca por um token OAuth do Databricks com all-apis, que cobre as APIs usadas neste guia.

O servidor do seu aplicativo também deve conseguir alcançar o workspace. Se as listas de acesso de IP estiverem habilitadas, permita o IP de saída. Consulte rede MCP.

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

Configure seu aplicativo

Mantenha o token e o cliente específicos para o usuário conectado durante os passos.

Obter um token do Databricks para o usuário

Escolha a opção que corresponde à forma como o seu aplicativo autentica os usuários. Ambas as opções dão a você databricks_token para os passos restantes.

Databricks Apps

O Databricks Apps fornece o token do Databricks do usuário no cabeçalho da solicitação x-forwarded-access-token. Use esse token diretamente. Seu aplicativo não precisa realizar a troca de tokens.

Leia o token dentro da solicitação atual. Por exemplo, em um manipulador de solicitações Flask:

Python

from flask import request

databricks_token = request.headers.get("x-forwarded-access-token")
if not databricks_token:
    raise ValueError("A Databricks user token is required.")

Para outras estruturas, consulte Recuperar credenciais de autorização de usuário.

External identity provider

Se você já tiver um token OAuth do Databricks para o usuário, use-o diretamente. Caso contrário, troque o token do provedor de identidade do usuário por um token OAuth do Databricks:

Python

import requests

response = requests.post(
    "https://<workspace-hostname>/oidc/v1/token",
    data={
        "subject_token": idp_token,
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "scope": "all-apis",
    },
)
response.raise_for_status()
databricks_token = response.json()["access_token"]

Use databricks_token nos os passos seguintes. A troca não devolve um token de refresh. Use expires_in da resposta para controlar a expiração e repita a troca com um token de provedor de identidade válido conforme necessário. Consulte Requisitos e limitações da troca de tokens.

Listar MCPs

Liste os MCPs que o usuário pode acessar em um esquema. Para MCPs fornecidos pelo Databricks, use schemas/system.ai. Para MCPs registrados, use o esquema onde estão registrados, como schemas/main.default.

Databricks SDK

Instale o SDK:

Bash

pip install --upgrade databricks-sdk

Crie um cliente com o token do usuário e liste os MCPs:

Python

from databricks.sdk import WorkspaceClient

workspace_client = WorkspaceClient(
    host="https://<workspace-hostname>",
    token=databricks_token,
    auth_type="pat",
)

for service in workspace_client.ai_gateway.list_mcp_services(parent="schemas/system.ai"):
    print(service.name)

A configuração auth_type="pat" do SDK seleciona o token fornecido em vez das credenciais de ambiente do aplicativo. O token fornecido continua a ser o token OAuth do usuário. Crie um WorkspaceClient para cada usuário de forma que cada chamada use o token desse usuário. Os seguintes passos reutilizam workspace_client. O SDK processa a paginação para você.

Python

Chame a API REST com o token do usuário e liste os MCPs:

Python

import requests

url = "https://<workspace-hostname>/api/2.1/unity-catalog/mcp-services"
headers = {"Authorization": f"Bearer {databricks_token}"}
params = {"parent": "schemas/system.ai"}

while True:
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    body = response.json()
    for service in body.get("mcp_services", []):
        print(service["name"])
    if not body.get("next_page_token"):
        break
    params["page_token"] = body["next_page_token"]

Consulte Listar serviços MCP.

Verificar o status de login do usuário

Para MCPs que usam OAuth por usuário, como system.ai.github, verifique se o usuário está conectado ao provedor externo:

Databricks SDK

Obtenha a credencial do usuário para o MCP:

Python

from databricks.sdk.errors import NotFound
from databricks.sdk.service.catalog import ProvisioningInfoState

try:
    credential = workspace_client.ai_gateway.get_mcp_service_user_mapped_credential(
        name="mcp-services/system.ai.github"
    )
    signed_in = (
        credential.provisioning_info is not None
        and credential.provisioning_info.state == ProvisioningInfoState.ACTIVE
    )
except NotFound:
    signed_in = False

Python

Chame a API REST com o token do usuário:

Python

import requests

response = requests.get(
    "https://<workspace-hostname>/api/2.1/unity-catalog/mcp-services/system.ai.github/user-credentials",
    headers={"Authorization": f"Bearer {databricks_token}"},
)
if response.status_code == 404:
    signed_in = False
else:
    response.raise_for_status()
    signed_in = response.json().get("provisioning_info", {}).get("state") == "ACTIVE"

• Se provisioning_info.state for ACTIVE, o usuário está conectado. Vá para Ferramentas de chamada.
• Se a solicitação retornar NOT_FOUND ou o estado for diferente de ACTIVE, mostre um botão de login para o MCP.

Os MCPs que não usam OAuth por usuário, como os MCPs de dados e ferramentas do Databricks, não precisam desse o passo. Consulte Obter a credencial do autor da chamada.

Faça logon do usuário no provedor

Quando o usuário clicar em seu botão de entrada, abra a página de entrada do MCP em um pop-up. O usuário entra nessa página e autoriza o acesso na tela de consentimento do provedor.

JavaScript

const signInUrl = `https://${workspaceHostname}/mcp-service-login?name=${encodeURIComponent(mcpName)}`;
window.open(signInUrl, 'mcp-sign-in', 'popup,width=600,height=700');

A página de login não envia uma mensagem de volta para o seu aplicativo. Para detectar quando o login termina, verifique o status do login novamente quando o usuário retornar ao seu aplicativo.

A página de login usa a sessão do navegador Databricks do usuário. Se o usuário não estiver conectado ao workspace nesse navegador, o Databricks solicitará que ele faça login primeiro. A credencial do provedor é salva para o usuário que está conectado na página, então esse usuário deve ser o mesmo usuário que seu aplicativo representa.

Ferramentas de chamada

Envie solicitações de MCP para a URL do MCP, https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>, com o token do Databricks do usuário.

Seu aplicativo pode chamar ferramentas diretamente, conforme mostrado nesta etapa, ou entregá-las a um agente que decide quais ferramentas chamar. Para a execução de um agente, siga o o passo 3: execução de um agente com estas ferramentas e passe os workspace_client tokens que você criou com o token do usuário em Listar MCPs, para que o agente chame ferramentas como esse usuário. As estruturas de agente usam a versão 1 do MCP Python SDK, então instale os pacotes listados nessa página.

Databricks SDK

Instale os pacotes:

Bash

pip install --upgrade databricks-mcp

Conecte-se com o workspace_client do usuário em Listar MCPs, depois liste e chame as ferramentas:

Python

from databricks_mcp import DatabricksMCPClient

mcp_client = DatabricksMCPClient(
    server_url="https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.github",
    workspace_client=workspace_client,
)

for tool in mcp_client.list_tools():
    print(f"{tool.name}: {tool.description}")

result = mcp_client.call_tool("<tool-name>", arguments={})
print(result)

Python

Este exemplo usa a versão 2 do MCP Python SDK:

Bash

pip install --upgrade "mcp>=2"

Abra uma sessão com o tokens do usuário e, em seguida, liste e chame as ferramentas:

Python

import asyncio

import httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.github"


async def main(databricks_token):
    http_client = httpx2.AsyncClient(headers={"Authorization": f"Bearer {databricks_token}"})
    async with http_client, streamable_http_client(MCP_URL, http_client=http_client) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            result = await session.list_tools()
            for tool in result.tools:
                print(f"{tool.name}: {tool.description}")

            result = await session.call_tool("<tool-name>", arguments={})
            print(result)


asyncio.run(main(databricks_token))

Descubra os nomes das ferramentas e os esquemas de entrada com list_tools() antes de chamar uma ferramenta e verifique isError em cada resultado. Para saber como ler os resultados, consulte Chamar uma ferramenta diretamente para solucionar problemas. Se a lista de ferramentas estiver vazia ou a conexão falhar, consulte Autenticação do MCP.

Outros recursos

• Referência de API e SDK de MCP
• Iniciar sessão num provedor externo
• Chamar ferramentas MCP de um agente Python
• Autenticação para agentes