Pular para o conteúdo principal
Última atualização em

Hospede um servidor MCP no Databricks Apps

Crie um servidor MCP no Databricks Apps para que seu agente possa chamar suas próprias ferramentas. O Databricks Apps fornece o compute para executar o servidor e um URL HTTPS para que os agentes se conectem a ele.

Escolha seu caminho​

Escolha uma destas três maneiras de hospedar um servidor MCP em Databricks Apps:

Criar um servidor a partir do padrão Starter​

O padrão do servidor MCP (Iniciador) inclui uma ferramenta de integridade funcional que você pode chamar antes de adicionar seu próprio código Python.

Encontre e implante o padrão​

Use um workspace que atenda aos requisitos do Databricks Apps.

  1. In your workspace, open Unity Gateway and select MCPs .
  2. Clique em + MCP e escolha Build a new MCP server . A página de criação de Databricks Apps é aberta.
  3. Encontre Install from a padrão . Nesta galeria de padrões, selecione a tab Agents e, em seguida, MCP Server (Starter) .
  4. Revise as configurações de recurso, compute e autorização. Clique em Avançar para continuar na configuração.
  5. Dê ao aplicativo o nome mcp-my-server e clique em Create app . Use outro nome começando com mcp- se esse nome estiver em uso. Este prefixo permite que o AI Playground reconheça o servidor MCP.

A criação do aplicativo também é implantado o código de padrão. Aguarde a conclusão da implantação na página Visão geral do aplicativo; é nela que você encontrará a URL e o status da implantação.

Chamar a primeira ferramenta​

Copie a URL do aplicativo na página Overview e acrescente /mcp:

Text
https://<app-hostname>/mcp

Conecte seu agente com esta URL.

Peça ao seu agente: "Call the health tool." Confirme que a ferramenta retorna "status": "healthy".

Adicione sua própria ferramenta​

Adicione uma ferramenta que converta texto para maiúsculas:

  1. Na página Overview do aplicativo, siga Edit in your IDE para copiar o código-fonte para o seu computador e sincronizar as edições de volta com o workspace.

  2. Abra server/tools.py. Adicione esta função dentro de load_tools(mcp_server), junto com as ferramentas existentes:

    Python
        @mcp_server.tool
        def uppercase(text: str) -> str:
            """Convert a string to uppercase."""
            return text.upper()

  3. Sincronize suas alterações e reimplante o app.

  4. Reconecte seu agente para carregar as ferramentas atualizadas. Peça para ele chamar uppercase com hello e confirme se o resultado é HELLO.

Consulte o código-fonte do modelo padrão para obter o servidor completo.

Exponha uma API REST como ferramentas MCP​

Use esta opção quando você já tiver uma API HTTP, como uma API de consulta de clientes, e quiser que seu agente a chame. O padrão MCP Server (OpenAPI) fornece ferramentas para descobrir e chamar os endpoints da sua API.

Preparar a API​

O padrão precisa de duas coisas:

  • Uma descrição da API: salve a especificação OpenAPI 3.x da sua API como spec.json e faça o upload para um volume. Coloque-o na raiz do volume, fora de qualquer subpasta. Veja a especificação de exemplo.
  • Uma conexão HTTP: crie uma conexão que armazene as credenciais de autenticação da sua API ou use uma existente. Armazene o token de backend ou as credenciais do cliente OAuth nesta conexão. Copie o nome da conexão. Criar um requer CREATE CONNECTION.

Escolha o método de autenticação da conexão para a identidade que sua API deve receber:

  • account do provedor de cada usuário: Escolha OAuth User-to-Machine Per User e configure as configurações de OAuth do provedor.
  • Uma account compartilhada: escolha Token de portador , OAuth máquina para máquina ou OAuth usuário para máquina compartilhada , dependendo do que a API oferece suporte.

Consulte Métodos de autenticação de conexão HTTP para as opções suportadas e propriedades de conexão para as credenciais e Endpoint OAuth necessários.

Criar o aplicativo​

  1. Em Unity Gateway , selecione MCPs , clique em + MCP e escolha Build a new MCP server .
  2. On the Apps creation page, under Install from a padrão , select Agents , then MCP Server (OpenAPI) .
  3. Para o recurso uc-volume , selecione o volume contendo spec.json. Isso dá ao aplicativo acesso à descrição da sua API.
  4. Continue pelas configurações de compute e autorização. Nomeie o aplicativo mcp-my-api e clique em Create app .

Configurar autenticação e a conexão​

O padrão usa o token do Databricks do chamador para acessar a conexão HTTP. A conexão fornece a credencial da API externa. Isso se aplica mesmo quando todos os chamadores usam uma account de backend compartilhada.

  1. Em autorização de usuário, verifique se o aplicativo solicita catalog.connections, o escopo declarado pelo padrão.

  2. Conceda a cada chamador PODE USAR no aplicativo e USE CONNECTION na conexão HTTP. Para conceder acesso de conexão, abra Catálogo > Conexões , selecione a conexão e use sua tab Permissões .

  3. Na página Overview do aplicativo, siga Edit in your IDE para copiar o código-fonte para o seu computador e configurar a sincronização com o workspace.

  4. Abra app.yaml. Na seção env, localize UC_CONNECTION_NAME e defina seu valor como o nome da sua conexão:

    YAML
    - name: UC_CONNECTION_NAME
      value: my_api_connection

    Substitua my_api_connection pelo nome da sua conexão. Deixe as outras configurações de padrão inalteradas.

  5. Sincronize o arquivo atualizado e, em seguida, reimplante o aplicativo. Aguarde a conclusão da implantação em Visão geral .

Faça a primeira chamada​

Conecte-se com um token OAuth do Databricks que inclua os escopos de autorização do usuário do aplicativo. Consulte Escopos OAuth para chamadas de aplicativos. Para uma conexão por usuário, cada chamador também deve autorizar sua account de provedor usando o fluxo de entrada OAuth da conexão HTTP.

  1. Copie o URL do aplicativo em Visão geral , adicione /mcp e conecte seu agente.
  2. Peça ao seu agente para chamar list_api_endpoints. Verifique se o resultado inclui os Endpoint na sua especificação.
  3. Peça ao agente para chamar um endpoint somente leitura e confirme se ele retorna dados da sua API.

O padrão lê o token do usuário de x-forwarded-access-token e chama serving_endpoints.http_request com o nome da conexão. Veja o auxiliar de autenticação e o manipulador de solicitação de API.

Para códigos novos que chamam a API fora deste padrão, o Databricks recomenda o proxy de conexão HTTP.

Especificação OpenAPI de exemplo​

Esta especificação descreve GET /widgets. Substitua a URL e as operações pelos valores da sua API:

JSON
{
  "openapi": "3.1.0",
  "info": { "title": "Example API", "version": "1.0.0" },
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/widgets": {
      "get": {
        "summary": "List widgets",
        "responses": { "200": { "description": "A list of widgets" } }
      }
    }
  }
}

Implantar um servidor MCP existente​

Hospede seu servidor MCP existente no Databricks Apps.

Preparar seu servidor​

Sua pasta de origem precisa de:

  • Um servidor HTTP: Configure o HTTP 스트리mável. Escute em 0.0.0.0 e na porta em DATABRICKS_APP_PORT (default 8000). Observe o seu caminho MCP, como /mcp.

  • Dependências: Inclua o arquivo de dependência apropriado, como requirements.txt para o Python ou package.json para o Node.js.

  • Um comando de começar: Adicione app.yaml com o comando que inicia o seu servidor. Para um ponto de entrada Python denominado server.py, use:

    YAML
    command: ['python', 'server.py']

Implantar e conectar​

  1. Em Unity Gateway , selecione MCPs , clique em + MCP e escolha Build a new MCP server .
  2. On the Apps creation page, choose Create a custom app . Name it with the mcp- prefix and complete the app setup.
  3. Na página Overview do aplicativo, siga Edit in your IDE para sincronizar sua pasta de código-fonte com o workspace.
  4. Clique em Implantar , selecione a pasta do workspace e clique em Selecionar e Implantar . Aguarde a conclusão da implantação. Consulte as instruções de implantação.
  5. Copie a URL do aplicativo e adicione seu caminho do MCP. Conecte seu agente com essa URL e chame uma das ferramentas do seu servidor para verificar a conexão.

Conecte seu agente​

Use a URL do MCP para o caminho escolhido. Para os padrões Starter e OpenAPI, adicione /mcp à URL do aplicativo. Para um servidor existente, use o caminho do MCP configurado no seu servidor.

Escolha o guia de configuração do seu agente:

Os chamadores precisam de PODE USAR no aplicativo e um token OAuth. Tokens de acesso pessoal não são suportados. Consulte Permissões de aplicativos e autenticação de tokens para aplicativos.

Preços e monitoramento​

Os aplicativos usam preços do Databricks Apps. Para obter os logs de implantação e de solicitação, consulte Registro em log e monitoramento para Databricks Apps.

Nesta página