Pular para o conteúdo principal

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:

  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.

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.

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.

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.

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ê.

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:

Obtenha a credencial do usuário para o MCP:

Python
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
  • 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.
  • 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.

JavaScript
// 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.

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

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.

Outros recursos​