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
EXECUTEnos MCPs, além deUSE CATALOGeUSE SCHEMAem 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
- External identity provider
- 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.
- Adicione os escopos de autorização do usuário:
ai-gatewaypara chamadas de ferramentas eunity-catalogpara APIs de status de descoberta e entrada. - Conceda a cada usuário CAN USE no aplicativo.
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:
- 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.
- 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.
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 account. O Unity Gateway em si está disponível de forma geral. Consulte Gerenciar prévias do 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
- External identity provider
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:
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.
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:
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
- Python
Instale o SDK:
pip install --upgrade databricks-sdk
Crie um cliente com o token do usuário e liste os MCPs:
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ê.
Chame a API REST com o token do usuário e liste os MCPs:
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"]
Cada name é um caminho de recurso da forma mcp-services/<catalog>.<schema>.<service>, como mcp-services/system.ai.github. Passe-o inalterado para a API de status de login e use-o para construir a URL do MCP em Chamar ferramentas. Veja Listar serviços MCP.
Verificar o status de login do usuário
Verifique cada MCP que seu aplicativo usa. A resposta mostra se o MCP usa OAuth por usuário e, se usar, se o usuário está conectado ao provedor externo:
- Databricks SDK
- Python
Obtenha a credencial do usuário para o MCP:
from databricks.sdk.errors import InvalidParameterValue, NotFound
from databricks.sdk.service.catalog import ProvisioningInfoState
mcp_name = service.name # From List MCPs, for example "mcp-services/system.ai.github"
needs_sign_in = True
try:
credential = workspace_client.ai_gateway.get_mcp_service_user_mapped_credential(
name=mcp_name
)
signed_in = (
credential.provisioning_info is not None
and credential.provisioning_info.state == ProvisioningInfoState.ACTIVE
)
except NotFound:
signed_in = False
except InvalidParameterValue:
# The MCP doesn't use per-user OAuth.
needs_sign_in = False
signed_in = True
Chame a API REST com o token do usuário:
import requests
mcp_name = service["name"] # From List MCPs, for example "mcp-services/system.ai.github"
response = requests.get(
f"https://<workspace-hostname>/api/2.1/unity-catalog/{mcp_name}/user-credentials",
headers={"Authorization": f"Bearer {databricks_token}"},
)
needs_sign_in = True
if response.status_code == 404:
signed_in = False
elif (
response.status_code == 400
and response.json().get("error_code") == "INVALID_PARAMETER_VALUE"
):
# The MCP doesn't use per-user OAuth.
needs_sign_in = False
signed_in = True
else:
response.raise_for_status()
signed_in = response.json().get("provisioning_info", {}).get("state") == "ACTIVE"
- Se
provisioning_info.stateforACTIVE, o usuário está conectado. Vá para Ferramentas de chamada. - Se a solicitação retornar
NOT_FOUNDou o estado for diferente deACTIVE, mostre um botão de login para o MCP. - Se a solicitação retornar
INVALID_PARAMETER_VALUE, o MCP não usará OAuth por usuário, portanto, o usuário não precisará fazer login. Este é o caso dos MCPs de dados e ferramentas do Databricks. Acesse Ferramentas de chamada.
Consulte Obter a credencial do chamador.
Faça logon do usuário no provedor
Quando o usuário clicar no botão de login, abra a página de login do MCP em um pop-up. O parâmetro name da página é o nome do MCP sem o prefixo mcp-services/, como system.ai.github. O usuário faz login nessa página e autoriza o acesso na tela de consentimento do provedor.
// mcpName is the MCP name without the mcp-services/ prefix, for example "system.ai.github"
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 MCP para a URL do MCP usando o token do Databricks do usuário. A URL do MCP é https://<workspace-hostname>/ai-gateway/ seguida pelo nome de List MCPs, por exemplo, https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.github.
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
- Python
Instale os pacotes:
pip install --upgrade databricks-mcp
Conecte-se com o workspace_client do usuário em Listar MCPs, depois liste e chame as ferramentas:
from databricks_mcp import DatabricksMCPClient
mcp_name = "mcp-services/system.ai.github" # A name from List MCPs
mcp_client = DatabricksMCPClient(
server_url=f"https://<workspace-hostname>/ai-gateway/{mcp_name}",
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.isError)
print(result.content)
Este exemplo usa a versão 2 do MCP Python SDK:
pip install --upgrade "mcp>=2"
Abra uma sessão com o tokens do usuário e, em seguida, liste e chame as ferramentas:
import asyncio
import httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
mcp_name = "mcp-services/system.ai.github" # A name from List MCPs
MCP_URL = f"https://<workspace-hostname>/ai-gateway/{mcp_name}"
async def main(databricks_token):
http_client = httpx2.AsyncClient(
timeout=120.0,
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.is_error)
print(result.content)
asyncio.run(main(databricks_token))
As chamadas de ferramenta através do Unity Gateway podem levar mais tempo do que o timeout default de 5 segundos de httpx2.AsyncClient, então configure um timeout mais longo no cliente.
Descubra nomes de ferramentas e esquemas de entrada com list_tools() antes de chamar uma ferramenta e verifique se cada resultado é um erro: result.isError com databricks-mcp ou result.is_error com a versão 2 do MCP Python SDK. Para saber como ler resultados, consulte Chamar uma ferramenta diretamente para solucionar problemas. Se a lista de ferramentas estiver vazia ou a conexão falhar, consulte Autenticação MCP.