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

• Tenha a URL do seu servidor MCP e os detalhes de autenticação prontos ou use uma conexão HTTP existente.
• Verifique as permissões de registro ou as permissões de atualização e exclusão para sua operação.
• Instale e autentique a CLI do Databricks ou o SDK de sua escolha. Os trechos de código do SDK pressupõem um cliente de workspace autenticado.

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

REST API

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

Bash

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

CLI

Bash

databricks connections create --json @connection.json

Python SDK

Torne o token do portador do servidor disponível na variável de ambiente MCP_SERVER_TOKEN.

Python

import os
from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c

w = WorkspaceClient()

connection = w.connections.create(
    name="my_connection",
    parent="schemas/main.default",
    connection_type=c.ConnectionType.HTTP,
    options={
        "host": "https://mcp.example.com",
        "port": "443",
        "base_path": "/mcp",
        "bearer_token": os.environ["MCP_SERVER_TOKEN"],
    },
)

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.

REST API

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

CLI

Passe o esquema pai e o nome do MCP e forneça a configuração com --json. Defina include_tool_selectors para restringir as ferramentas ou omita-o para expor todas as ferramentas.

Bash

databricks ai-gateway create-mcp-service schemas/main.default my_mcp --json '{
  "comment": "External MCP server",
  "config": {
    "source_connection": {
      "name": "connections/main.default.my_connection"
    }
  }
}'

Terraform

Criar e gerenciar um MCP com o provedor Databricks Terraform e o databricks_ai_gateway_mcp_service recurso:

Hcl

resource "databricks_ai_gateway_mcp_service" "example" {
  parent         = "schemas/main.default"
  mcp_service_id = "my_mcp"
  comment        = "External MCP server"

  config = {
    source_connection = {
      name = "connections/main.default.my_connection"
    }
  }
}

Bundles (Beta)

Defina o MCP em um pacote e implante-o com databricks bundle deploy. Recursos do MCP exigem o Databricks CLI versão 1.17.0 e acima e o mecanismo de implantação direta.

YAML

resources:
  mcp_services:
    my_mcp:
      parent: schemas/main.default
      mcp_service_id: my_mcp
      comment: External MCP server
      config:
        source_connection:
          name: connections/main.default.my_connection

Python SDK

Crie e gerencie um MCP com o SDK do Databricks para Python:

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c

w = WorkspaceClient()

mcp_service = w.ai_gateway.create_mcp_service(
    parent="schemas/main.default",
    mcp_service_id="my_mcp",
    mcp_service=c.McpService(
        comment="External MCP server",
        config=c.McpServiceConfig(
            source_connection=c.McpServiceConfigSourceConnection(
                name="connections/main.default.my_connection"
            ),
        ),
    ),
)

Go SDK

Criar e gerenciar um MCP com o SDK do Databricks para Go:

Go

mcpService, err := w.AiGateway.CreateMcpService(ctx, catalog.CreateMcpServiceRequest{
	Parent:       "schemas/main.default",
	McpServiceId: "my_mcp",
	McpService: catalog.McpService{
		Comment: "External MCP server",
		Config: &catalog.McpServiceConfig{
			SourceConnection: &catalog.McpServiceConfigSourceConnection{
				Name: "connections/main.default.my_connection",
			},
		},
	},
})

Go Modular SDK

Crie e gerencie um serviço MCP com o SDK do Databricks AI Gateway para Go. Os campos opcionais são ponteiros; portanto, o exemplo usa um auxiliar de uma linha, func ptr[T any](v T) *T { return &v }.

Go

mcpService, err := c.CreateMcpService(ctx, aigateway.CreateMcpServiceRequest{
	Parent:       ptr("schemas/main.default"),
	McpServiceId: ptr("my_mcp"),
	McpService: &aigateway.McpService{
		Comment: ptr("External MCP server"),
		Config: &aigateway.McpServiceConfig{
			Source: &aigateway.McpServiceConfig_Source_SourceConnection{
				SourceConnection: aigateway.McpServiceConfig_SourceConnection{
					Name: ptr("connections/main.default.my_connection"),
				},
			},
		},
	},
})

Java SDK

Criar e gerenciar um MCP com o SDK do Databricks para Java:

Java

McpService mcpService =
    w.aiGateway()
        .createMcpService(
            new CreateMcpServiceRequest()
                .setParent("schemas/main.default")
                .setMcpServiceId("my_mcp")
                .setMcpService(
                    new McpService()
                        .setComment("External MCP server")
                        .setConfig(
                            new McpServiceConfig()
                                .setSourceConnection(
                                    new McpServiceConfigSourceConnection()
                                        .setName("connections/main.default.my_connection")))));

JS Modular SDK

Crie e gerencie um MCP com o JavaScript SDK:

TypeScript

const created = await client.createMcpService({
  parent: 'schemas/main.default',
  mcpServiceId: 'my_mcp',
  mcpService: {
    comment: 'External MCP server',
    config: {
      source: {
        $case: 'sourceConnection',
        sourceConnection: { 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.

REST API

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.

CLI

Bash

databricks ai-gateway list-mcp-services --parent schemas/main.default --view FULL

databricks ai-gateway get-mcp-service mcp-services/main.default.my_mcp

Python SDK

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c

w = WorkspaceClient()

for service in w.ai_gateway.list_mcp_services(
    parent="schemas/main.default",
    view=c.ListMcpServicesRequestView.FULL,
):
    print(service.name)

service = w.ai_gateway.get_mcp_service(name="mcp-services/main.default.my_mcp")

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.

REST API

Bash

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

CLI

Conceda EXECUTE com a CLI do Databricks:

Bash

databricks grants update mcp_service main.default.my_mcp \
  --json '{"changes": [{"principal": "data-team", "add": ["EXECUTE"]}]}'

Terraform

Grant EXECUTE with the Databricks Terraform provider and the databricks_grant recurso:

Hcl

resource "databricks_grant" "example" {
  mcp_service = "main.default.my_mcp"
  principal   = "data-team"
  privileges  = ["EXECUTE"]
}

Bundles (Beta)

Add a grants block to the MCP recurso in your bundle and redeploy to grant access.

YAML

resources:
  mcp_services:
    my_mcp:
      parent: schemas/main.default
      mcp_service_id: my_mcp
      comment: External MCP server
      config:
        source_connection:
          name: connections/main.default.my_connection
      grants:
        - principal: data-team
          privileges: [EXECUTE]

Python SDK

Conceda EXECUTE com o SDK do Databricks para Python:

Python

from databricks.sdk.service import catalog as c

w.grants.update(
    securable_type="mcp_service",
    full_name="main.default.my_mcp",
    changes=[c.PermissionsChange(principal="data-team", add=[c.Privilege.EXECUTE])],
)

Go SDK

Grant EXECUTE with the Databricks SDK for Go:

Go

_, err := w.Grants.Update(ctx, catalog.UpdatePermissions{
	SecurableType: "mcp_service",
	FullName:      "main.default.my_mcp",
	Changes: []catalog.PermissionsChange{{
		Principal: "data-team",
		Add:       []catalog.Privilege{catalog.PrivilegeExecute},
	}},
})

Java SDK

Conceda EXECUTE com o SDK do Databricks para Java:

Java

w.grants().update(
    new UpdatePermissions()
        .setSecurableType("mcp_service")
        .setFullName("main.default.my_mcp")
        .setChanges(Arrays.asList(
            new PermissionsChange().setPrincipal("data-team").setAdd(Arrays.asList(Privilege.EXECUTE)))));

Gerenciar início de sessão do provedor

Para MCPs que utilizam OAuth por usuário, cada chamador faz login no provedor externo. Para entrada interativa, siga Configuração de serviços externos.

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.

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.

REST API

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

CLI

Bash

databricks ai-gateway update-mcp-service mcp-services/main.default.my_mcp comment \
  --json '{"comment": "Updated: governs an MCP server"}'

Terraform

Edite comment (ou qualquer outro campo mutável) no recurso databricks_ai_gateway_mcp_service e aplique novamente. As alterações se aplicam no local.

Bundles (Beta)

Edite comment (ou qualquer outro campo mutável) no recurso do bundle e execute a execução de databricks bundle deploy. As alterações são aplicadas diretamente.

Python SDK

Python

from databricks.sdk.service import catalog as c
from databricks.sdk.common.types.fieldmask import FieldMask

updated = w.ai_gateway.update_mcp_service(
    name="mcp-services/main.default.my_mcp",
    update_mask=FieldMask(["comment"]),
    mcp_service=c.McpService(comment="Updated: governs an MCP server"),
)

Go SDK

Go

updated, err := w.AiGateway.UpdateMcpService(ctx, catalog.UpdateMcpServiceRequest{
	Name:       "mcp-services/main.default.my_mcp",
	UpdateMask: *fieldmask.New([]string{"comment"}),
	McpService: catalog.McpService{Comment: "Updated: governs an MCP server"},
})

Go Modular SDK

Go

mask, err := types.NewFieldMask[aigateway.McpService]("comment")
updated, err := c.UpdateMcpService(ctx, aigateway.UpdateMcpServiceRequest{
	McpService: &aigateway.McpService{
		Name:    ptr("mcp-services/main.default.my_mcp"),
		Comment: ptr("Updated: governs an MCP server"),
	},
	UpdateMask: mask,
})

Java SDK

Java

McpService updated =
    w.aiGateway()
        .updateMcpService(
            new UpdateMcpServiceRequest()
                .setName("mcp-services/main.default.my_mcp")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setMcpService(new McpService().setComment("Updated: governs an MCP server")));

JS Modular SDK

TypeScript

import { mcpServiceFieldMask } from '@databricks/sdk-aigateway/v1';

const updated = await client.updateMcpService({
  mcpService: {
    name: 'mcp-services/main.default.my_mcp',
    comment: 'Updated: governs an MCP server',
  },
  updateMask: mcpServiceFieldMask('comment'),
});

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.

REST API

Bash

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

CLI

Bash

databricks ai-gateway delete-mcp-service mcp-services/main.default.my_mcp

Terraform

Remova o recurso MCP da sua configuração e realize a execução terraform apply. Revise o plano antes de aplicá-lo.

Bundles (Beta)

Remova o recurso de MCP do pacote e execução databricks bundle deploy. Revise as alterações de implantação antes de aplicá-las.

Python SDK

Python

w.ai_gateway.delete_mcp_service(name="mcp-services/main.default.my_mcp")

Go SDK

Go

err := w.AiGateway.DeleteMcpService(ctx, catalog.DeleteMcpServiceRequest{
	Name: "mcp-services/main.default.my_mcp",
})

Go Modular SDK

Go

err := c.DeleteMcpService(ctx, aigateway.DeleteMcpServiceRequest{
	Name: ptr("mcp-services/main.default.my_mcp"),
})

Java SDK

Java

w.aiGateway().deleteMcpService(new DeleteMcpServiceRequest().setName("mcp-services/main.default.my_mcp"));

JS Modular SDK

TypeScript

await client.deleteMcpService({ name: 'mcp-services/main.default.my_mcp' });

Outros recursos

• API REST do MCP
• Configuração de conexão HTTP e autenticação
• Usar ferramentas MCP em um agente Python