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

Referência de API e SDK de MCP

Use estes exemplos para automatizar a configuração do MCP. A API representa cada MCP como um recurso McpService. Para a interface do Workspace, consulte Servidores MCP externos. Para controles de acesso e políticas, consulte Fazer a governança de um MCP.

Pré-requisitos​

Substitua main.default.my_mcp, o nome da conexão e data-team pelos seus próprios valores. Não há suporte para a criação de MCPs com comandos SQL como CREATE MCP SERVICE.

Operações da API​

A API REST do MCP fornece estas operações. Siga cada link para ver seus campos, permissões e respostas.

Operação

Use-o para

Criar

Registro um servidor MCP por meio de uma conexão HTTP.

Lista

Encontre MCPs que você pode acessar em um esquema.

Get

Ler a configuração de um MCP e o etag atual.

Atualizar

Altere o comentário, a conexão, a seleção de ferramentas ou os limites de taxa.

Deletar

Remova um MCP registrado.

Iniciar sessão

Faça login ou autentique novamente o chamador com o provedor.

Verificar login

Leia o estado de login do provedor do chamador.

Encerrar sessão

Revogue a credencial de provedor do chamador.

Operação

Use-o para

Criar

Registro um servidor MCP por meio de uma conexão HTTP.

Lista

Encontre MCPs que você pode acessar em um esquema.

Get

Ler a configuração de um MCP e o etag atual.

Atualizar

Altere o comentário, a conexão, a seleção de ferramentas ou os limites de taxa.

Deletar

Remova um MCP registrado.

Iniciar sessão

Faça login ou autentique novamente o chamador com o provedor.

Verificar login

Leia o estado de login do provedor do chamador.

Encerrar sessão

Revogue a credencial de provedor do chamador.

Para descobrir e chamar ferramentas, use um cliente MCP com a URL do MCP, https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>. Essas APIs de gerenciamento usam o escopo OAuth unity-catalog. As chamadas de ferramenta do MCP usam ai-gateway.

Criar uma conexão​

Create a schema-level HTTP connection to your MCP server. These examples connect to https://mcp.example.com/mcp with a bearer token. For OAuth and other authentication settings, see HTTP connection settings.

Para REST ou CLI, salve esta solicitação como connection.json, substituindo a URL e o token pelos valores do seu servidor. Mantenha este arquivo de credenciais fora do controle de versão.

JSON
{
  "name": "my_connection",
  "parent": "schemas/main.default",
  "connection_type": "HTTP",
  "options": {
    "host": "https://mcp.example.com",
    "port": "443",
    "base_path": "/mcp",
    "bearer_token": "<mcp-server-token>"
  }
}

Envie a solicitação para a API de conexões:

Bash
databricks api post /api/2.1/unity-catalog/connections --json @connection.json

The connection's full name is main.default.my_connection. Reference it as connections/main.default.my_connection when creating the MCP abaixo. If the connection already exists, use its name and skip this o passo.

Criar um MCP​

O MCP faz referência a uma conexão HTTP existente. Para limitar as ferramentas que ele expõe, configure a seleção de ferramentas.

Envie um POST para /api/2.1/unity-catalog/mcp-services, passando parent e mcp_service_id como parâmetros de query. config.source_connection.name identifica a conexão HTTP do Unity Catalog com o servidor MCP. Defina include_tool_selectors para restringir as ferramentas ou omita-o para expor todas as ferramentas. Consulte Escolher ferramentas disponíveis.

Bash
databricks api post \
  "/api/2.1/unity-catalog/mcp-services?parent=schemas/main.default&mcp_service_id=my_mcp" \
  --json '{
  "comment": "External MCP server",
  "config": {
    "source_connection": {
      "name": "connections/main.default.my_connection"
    }
  }
}'

Encontre um MCP​

Liste os MCPs aos quais você pode acessar em um esquema e, em seguida, obtenha a configuração de um MCP pelo nome do seu recurso. Para MCPs integrados, use schemas/system.ai como pai.

Bash
databricks api get \
  "/api/2.1/unity-catalog/mcp-services?parent=schemas/main.default&view=FULL"

databricks api get "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp"

Quando a resposta da lista incluir next_page_token, repasse-a como page_token na próxima solicitação. Continue até que next_page_token esteja ausente ou vazio.

As respostas de listagem usam a view BASIC por default, o que omite detalhes de conexão de origem e nomes principais de limite de taxa. Use FULL para incluir esses campos. A CLI e o iterador Python lidam com a paginação para você.

Conceder acesso​

Estes exemplos concedem EXECUTE no MCP. Para ver os requisitos completos de acesso, incluindo as permissões pai, consulte Compartilhar um MCP.

Bash
databricks api patch \
  "/api/2.1/unity-catalog/permissions/mcp_service/main.default.my_mcp" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["EXECUTE"] }
    ]
  }'

Gerenciar início de sessão do provedor​

Para MCPs que usam OAuth por usuário, cada chamador faz login no provedor externo e autoriza sua account de provedor. O chamador precisa de permissão para chamar o MCP.

Entrar no Unity Gateway​

Esta opção requer o direito de acesso ao Workspace.

  1. Abra o Unity Gateway no seu workspace e selecione MCPs .
  2. Clique no MCP e, em seguida, clique em Login e autorize o acesso à sua account de provedor.
  3. Tente novamente a chamada da ferramenta após entrar.

Usar a página de login​

A página de login funciona para usuários com acesso ao Workspace , acesso de consumidor ou acesso ao Databricks SQL . Usuários com apenas acesso de consumidor ou acesso ao Databricks SQL podem usá-lo sem abrir a UI do Unity Gateway. Chamadas de ferramenta que requerem login de provedor retornam um link para esta página. Você também pode abri-lo antes da sua primeira chamada ou para entrar novamente:

  1. Abra a página de login do MCP:

    Text
    https://<workspace-hostname>/mcp-service-login?name=<catalog>.<schema>.<service>

    Substitua <workspace-hostname> pelo seu hostname do workspace e <catalog>.<schema>.<service> pelo nome completo do MCP, como system.ai.github.

  2. Clique em Sign in (Entrar) ou Login (Acessar) e autorize o acesso à sua account de provedor.

  3. Quando a página mostrar Você está conectado , feche-a e tente novamente a chamada.

Para permitir que usuários apenas com acesso de consumidor façam login em um MCP registrado, conceda ao grupo account users permissão para chamar o MCP. Para remover as credenciais do seu provedor, abra a página de login e clique em Sair . Nenhum login é necessário significa que o MCP não usa OAuth por usuário.

A página usa a sessão de navegador do Databricks do usuário e solicita que ele faça login no workspace, se necessário. Se seu aplicativo chama MCPs em nome de um usuário, o usuário conectado nesta página deve corresponder ao usuário representado pelo token do aplicativo. Para obter o código de integração, use os exemplos de pop-up e status de login.

Gerenciar credenciais com a API​

As APIs de credenciais estão em Beta. Para integrá-los ao seu próprio fluxo OAuth:

  1. Crie a credencial do chamador com os campos de troca de OAuth: authorization_code, pkce_verifier e oauth_redirect_uri.
  2. Verifique o status das credenciais. provisioning_info.state deve ser ACTIVE antes que a credencial possa ser usada. NOT_FOUND significa que o chamador ainda não tem credencial.
  3. Para sair, exclua a credencial do chamador.

Estas operações gerenciam a credencial do usuário chamador. O chamador precisa de acesso ao MCP.

Para usar a página de login do Databricks em vez do seu próprio fluxo OAuth, consulte Conectar seu aplicativo às ferramentas MCP.

Atualizar um MCP​

Estes exemplos atualizam o comentário do MCP. O nome do MCP não pode ser alterado.

Defina update_mask para os campos que você deseja alterar, como comment, config.source_connection.name, config.include_tool_selectors ou config.rate_limits. O uso de config substitui toda a configuração e limpa os campos opcionais omitidos. Ao alterar a conexão, o proprietário do MCP também precisa de USE CONNECTION na nova conexão.

Para uma atualização condicional, primeiro obtenha o MCP e passe seu etag com a atualização. A atualização só será bem-sucedida se o MCP não tiver sido alterado desde essa leitura. Codifique em URL o etag ao adicioná-lo a uma query string REST.

Bash
databricks api patch \
  "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp?update_mask=comment" \
  --json '{"comment": "Updated: governs an MCP server"}'

Exemplo: atualizar seleção de ferramenta​

Para expor apenas ferramentas cujos nomes comecem com get_:

Bash
databricks api patch \
  "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp?update_mask=config.include_tool_selectors" \
  --json '{
    "config": {
      "include_tool_selectors": ["get_*"]
    }
  }'

Uma lista include_tool_selectors vazia expõe todas as ferramentas. Consulte Escolher ferramentas disponíveis para ver os passos da interface do usuário.

Excluir um MCP​

Exclua apenas o MCP que você pretende remover. Os clientes configurados com sua URL não podem mais chamá-lo.

Você também pode passar o etag atual do MCP para tornar a exclusão condicional para que ele não tenha sido alterado desde a última leitura. Codifique o URL para etag em REST query strings.

Bash
databricks api delete "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp"

Outros recursos​

Nesta página