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

Hospede seu próprio servidor MCP

Hospede servidores MCP personalizados ou de terceiros como aplicativos do Databricks. Os servidores MCP personalizados são úteis se você já tiver um servidor MCP que queira implantar, se quiser executar um servidor MCP de terceiros como uma fonte de ferramentas ou se quiser encapsular uma API REST existente como ferramentas MCP.

O acesso a servidores MCP personalizados é controlado por meio das permissões do Databricks Apps. Para monitorar a atividade de MCP personalizada juntamente com seus outros servidores MCP e Endpoint de LLM, use o Unity Gateway.

Para usar um servidor MCP personalizado hospedado no código do agente, consulte Use MCP servers in Custom Agents.

Requisitos​

Crie um servidor MCP personalizado a partir do padrão Apps​

Use o padrão integrada do servidor MCP Hello World para criar e implantar um servidor MCP com ferramentas de exemplo já incluídas:

  1. Na barra lateral, clique em Compute .

  2. Clique na tab Aplicativos .

  3. Clique em Criar aplicativo .

  4. Na categoria Agents , selecione o padrão MCP Server - Hello World .

  5. Insira um nome de aplicativo começando com mcp- (por exemplo, mcp-hello-world).

nota

O nome do aplicativo deve começar com mcp- para ser reconhecido como um servidor MCP no AI Playground.

  1. Clique em Criar aplicativo .

O Databricks implanta o aplicativo com código de exemplo que você pode personalizar.

O padrão inclui duas ferramentas de exemplo para ajudar você a começar:

  • health() : Uma ferramenta de diagnóstico que confirma que o servidor está operacional e retorna informações de status.
  • get_current_user() : Uma ferramenta que recupera a informação do usuário atual usando o SDK do Databricks, demonstrando como integrar a autenticação do Workspace.

Adicionar uma ferramenta personalizada​

Para adicionar sua própria ferramenta, abra o código-fonte do aplicativo e defina uma nova função usando o decorador @mcp.tool(). Por exemplo, a ferramenta a seguir converte strings para maiúsculas:

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

Cada ferramenta deve incluir uma docstring. Os agentes utilizam a docstring para entender quando chamar a ferramenta. Após adicionar uma ferramenta, reimplante o aplicativo para disponibilizá-lo.

Consulte Criar um aplicativo a partir de um padrão para obter mais detalhes sobre como trabalhar com padrões de aplicativos, ou consulte o código-fonte do padrão no GitHub.

Empacote uma API REST como um servidor MCP a partir do padrão de aplicativos​

Use o template MCP Server (OpenAPI) padrão para expor qualquer API REST como ferramentas MCP sem precisar escrever código de ferramenta personalizado. Você fornece uma especificação OpenAPI que descreve a API e uma conexão Unity Catalog que se autentica nela, e o servidor transforma as operações da API em ferramentas que qualquer agente pode chamar.

O template implantado inclui um servidor MCP com três ferramentas:

  • list_api_endpoints : Lista os endpoints definidos na especificação OpenAPI.
  • get_api_endpoint_schema : Retorna o esquema de solicitação e resposta para um endpoint específico.
  • invoke_api_endpoint : Chama um endpoint com os parâmetros fornecidos e retorna a resposta.

Um agente chama list_api_endpoints e get_api_endpoint_schema para descobrir o que a API oferece e, em seguida, chama invoke_api_endpoint para executar uma operação.

Pré-requisitos​

Reúna as seguintes informações antes de criar o aplicativo:

  • Uma especificação OpenAPI 3.x para sua API REST, no formato JSON.
  • Um volume do Unity Catalog para armazenar o arquivo de especificação. Consulte O que são volumes do Unity Catalog?.
  • Uma conexão HTTP do Unity Catalog que se autentica na API. A conexão oferece suporte à autenticação por token de portador (bearer token), OAuth machine-to-machine (M2M) e OAuth user-to-machine (U2M). Para criar um, consulte Criar uma conexão com o serviço externo. A criação de uma conexão requer o privilégio CREATE CONNECTION; caso você não o tenha, peça a um administrador do workspace para criar a conexão.

A especificação deve ser um documento OpenAPI 3.x válido em JSON. No mínimo, ele declara a URL base da API em servers e as operações a serem expostas em paths:

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

Criar o servidor MCP​

  1. Faça o upload da sua especificação OpenAPI para o volume do Unity Catalog. Por default, o padrão lê spec.json da raiz do volume.

  2. Na barra lateral, clique em Compute .

  3. Clique na tab Aplicativos .

  4. Clique em Criar aplicativo .

  5. Na categoria Agents , selecione o padrão MCP Server (OpenAPI) .

  6. Para o recurso de volume do Unity Catalog, selecione o volume que contém seu arquivo de especificação. Consulte Adicionar recursos a um aplicativo Databricks.

  7. Insira um nome de aplicativo começando com mcp- (por exemplo, mcp-my-api).

nota

O nome do aplicativo deve começar com mcp- para ser reconhecido como um servidor MCP no AI Playground.

  1. Clique em Criar aplicativo .

Configurar a especificação e a conexão​

Depois que o Databricks implantar o aplicativo, defina as seguintes variáveis de ambiente no arquivo app.yaml e, em seguida, reimplemente o aplicativo:

  • SPEC_FILE_NAME : O caminho para o arquivo de especificação OpenAPI, relativo à raiz do volume do Unity Catalog. default to spec.json.
  • UC_CONNECTION_NAME : O nome da conexão HTTP do Unity Catalog que o servidor usa para se autenticar na API.

Depois que o aplicativo for reimplantado, o endpoint do servidor MCP estará disponível em https://<app-url>/mcp. Para chamar o servidor a partir do código do agente, consulte Usar servidores MCP em agentes personalizados. Para conectar um cliente externo como o Claude ou o Cursor, consulte Conectar MCPs a assistentes de AI e agentes de codificação.

Para obter detalhes de implementação, consulte o código-fonte do padrão no GitHub.

Hospede um servidor MCP existente como um aplicativo do Databricks​

Para hospedar um servidor MCP Python existente como um aplicativo do Databricks, siga os passos:

Configure seu ambiente​

Antes de fazer o deploy do seu servidor MCP, autentique-se no seu workspace usando OAuth.

  1. Faça a execução do seguinte em um terminal local:

    Bash
    databricks auth login --host https://<your-workspace-hostname>

Configure o servidor MCP​

Utilize o uv para gerenciamento de dependências e ferramentas unificadas ao implantar seu servidor MCP.

  1. Adicione um requirements.txt ao diretório raiz do servidor MCP e inclua uv como uma dependência.

    uv lida com a instalação de dependências adicionais definidas na configuração do seu projeto.

    Txt
    uv

  2. Crie um arquivo pyproject.toml que define um ponto de entrada de script para o seu servidor.

    Exemplo pyproject.toml:

    Toml
    [project.scripts]
    custom-server = "server.main:main"

    Neste exemplo:

    • custom-server é o nome do script que você usa com uv run
    • server.main:main especifica o caminho do módulo (server/main.py) e a função (main) para execução

  3. Adicione um arquivo app.yaml especificando o comando da CLI para execução do servidor MCP usando uv run.

    Por default, os aplicativos Databricks escutam na porta 8000. Se o servidor escutar em uma porta diferente, defina-a usando uma substituição de variável de ambiente no arquivo app.yaml.

    Exemplo app.yaml:

    YAML
    command: [
        'uv',
        'run',
        'custom-server', # This must match a script defined in pyproject.toml
      ]

Ao executar uv run custom-server, o uv procura a definição do script, encontra o caminho do módulo e chama a função main().

Faça o deploy do servidor MCP como um aplicativo do Databricks​

  1. Crie um aplicativo Databricks para hospedar o servidor MCP:

    Bash
    databricks apps create mcp-my-server
nota

Adicione o prefixo mcp- ao nome do seu aplicativo para identificá-lo claramente como um servidor MCP. Esta convenção de nomenclatura ajuda na descoberta e organização em seu workspace.

  1. Faça o upload do código-fonte para o Databricks e implante o aplicativo executando os seguintes comandos a partir do diretório que contém seu arquivo app.yaml:

    Bash
    DATABRICKS_USERNAME=$(databricks current-user me | jq -r .userName)
    databricks sync . "/Users/$DATABRICKS_USERNAME/mcp-my-server"
    databricks apps deploy mcp-my-server --source-code-path "/Workspace/Users/$DATABRICKS_USERNAME/mcp-my-server"

Encontrar a URL do seu aplicativo implantado​

Após a implantação, você pode encontrar a URL do seu aplicativo na interface do usuário do Databricks. O endpoint do servidor MCP está disponível em https://<app-url>/mcp.

preços​

Servidores MCP personalizados estão sujeitos aos preços do Databricks Apps.

Outros recursos​

Nesta página