Hospede servidores MCP personalizados utilizando aplicativos Databricks.

Hospede servidores MCP personalizados ou de terceiros como aplicativos Databricks. Servidores MCP personalizados são úteis se você já possui um servidor MCP que deseja implantar ou se deseja executar um servidor MCP de terceiros como fonte de ferramentas.

Requisitos

• Um servidor MCP hospedado como um aplicativo Databricks deve implementar um transporte compatível com HTTP, como o transporte HTTP transmissível.

Crie ou implemente um servidor MCP personalizado.

Escolha a opção que corresponde ao seu ponto de partida:

Criar a partir de um padrão : construir um novo servidor MCP do zero.

Crie um servidor MCP personalizado a partir dos aplicativos padrão.

Utilize o padrão integrado Hello World MCP Server 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 Agentes , selecione o padrão Hello World MCP Server .

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.

6. Clique em Criar aplicativo .

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

O documento inclui duas ferramentas de exemplo para você começar:

• health() : Uma ferramenta de diagnóstico que confirma se o servidor está operacional e retorna informações de status.
• get_current_user() : Uma ferramenta que recupera as informações do usuário atual usando o SDK Databricks , demonstrando como integrar a autenticação 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 seguinte ferramenta converte uma string em 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 AI usam a docstring para entender quando chamar a ferramenta. Após adicionar uma ferramenta, reimplemente o aplicativo para torná-la disponível.

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

Implantar um servidor existente : implantar um servidor MCP existente como um aplicativo Databricks .

Hospede um servidor MCP existente como um aplicativo Databricks.

Para hospedar um servidor Python MCP existente como um aplicativo Databricks, siga estas etapas:

Configure seu ambiente

Antes de instalar seu servidor MCP, autentique-se em seu workspace usando OAuth.

1. execute o seguinte em um terminal local:

   Bash

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

Configurar 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 Gerencia a instalação de dependências adicionais definidas na configuração do seu projeto.

   Txt

   uv
   

2. Crie um arquivo pyproject.toml que defina 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) a serem executados.

3. Adicione um arquivo app.yaml especificando o comando CLI para execução no 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
     ]

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

implantou o servidor MCP como um aplicativo Databricks

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

   Bash

   databricks apps create mcp-my-server

nota

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

2. Envie o código-fonte para Databricks e implante o aplicativo executando o seguinte comando a partir do diretório que contém o 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"

Encontre o URL do seu aplicativo implantado

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

Conecte-se ao servidor MCP personalizado

Clique na guia para ver como se conectar a um servidor MCP a partir de vários ambientes.

Local environment

Autentique-se no seu workspace usando OAuth conforme descrito em Configurar seu ambiente.

O exemplo a seguir mostra como se conectar ao servidor MCP personalizado e listar as ferramentas disponíveis:

Python

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient

# Replace with your deployed app URL
# Example: https://mcp-my-server-6051921418418893.aws.databricksapps.com/mcp
mcp_server_url = "https://<app-url>/mcp"

databricks_cli_profile = "DEFAULT"
workspace_client = WorkspaceClient(profile=databricks_cli_profile)

mcp_client = DatabricksMCPClient(server_url=mcp_server_url, workspace_client=workspace_client)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {tools}")

Notebook (service principal)

Use uma entidade de serviço para acessar o aplicativo Databricks hospedado em um Notebook Databricks . Passe os valores secretos do cliente diretamente, como mostrado abaixo, ou use os segredos do Databricks para recuperar as credenciais com segurança. Por exemplo: client_id=dbutils.secrets.get(scope="my-scope", key="client-id").

Python

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient

# Replace with your deployed app URL
mcp_server_url = "https://<app-url>/mcp"

workspace_client = WorkspaceClient(
    host="<workspace-url>",
    client_id="<client-id>",
    client_secret="<client-secret>"
)

mcp_client = DatabricksMCPClient(server_url=mcp_server_url, workspace_client=workspace_client)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {tools}")

Agent code (on-behalf-of-user)

Configure a autorização em nome do usuário. Consulte Autenticação em nome do usuário.

O exemplo a seguir mostra como habilitar o acesso em nome do usuário usando ModelServingUserCredentials para acessar o aplicativo Databricks hospedado de um agente:

Python

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient
from databricks.sdk.credentials_provider import ModelServingUserCredentials

# Replace with your deployed app URL
mcp_server_url = "https://<app-url>/mcp"

workspace_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

mcp_client = DatabricksMCPClient(server_url=mcp_server_url, workspace_client=workspace_client)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {tools}")

Registre o modelo do agente usando o escopo apps. Consulte Autenticação em nome do usuário.

Agent code (service principal)

Habilite a autenticação do sistema usando a entidade de serviço para acessar o aplicativo Databricks hospedado de um agente:

Python

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient

# Replace with your deployed app URL
mcp_server_url = "https://<app-url>/mcp"

workspace_client = WorkspaceClient()

mcp_client = DatabricksMCPClient(server_url=mcp_server_url, workspace_client=workspace_client)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {tools}")

Registre o modelo do agente usando DatabricksApps como um recurso. Consulte Passagem automática de autenticação.

Exemplo de Notebook: Crie um agente com servidores MCP Databricks

O Notebook a seguir mostra como criar agentes LangGraph e OpenAI que chamam ferramentas MCP com servidores MCP personalizados hospedados em aplicativos Databricks .

Agente de chamada de ferramentas LangGraph MCP

Abrir notebook em uma nova aba

Agente de chamada de ferramentas OpenAI MCP

Abrir notebook em uma nova aba

Próximos passos

• Conecte agentes a serviços externos para obter uma visão geral de todas as abordagens para conectar agentes a serviços externos, incluindo o gerenciamento OAuth e o proxy de conexões UC.

O livro de receitas do aplicativo fornece exemplos de código de ponta a ponta para integrar servidores MCP com diferentes estruturas:

• Exemplo de integração simplificada de MCP
• Exemplo de integração do Dash MCP

Para obter o código-fonte completo e exemplos adicionais, consulte o repositório Databricks Apps Cookbook.