Registro de um servidor MCP externo

Esta página descreve como registrar um servidor MCP auto-hospedado ou de terceiros como um serviço MCP no Unity Catalog e, em seguida, invocá-lo a partir do AI Playground, da linha de comando ou do código do seu agente. Registrar o servidor como um objeto protegido do Unity Catalog permite que o Unity Gateway faça proxy de cada chamada com credenciais gerenciadas, para que os agentes nunca manipulem os tokens do servidor. Para restringir quais ferramentas o serviço expõe e governar chamadas individuais, consulte Governar um serviço MCP.

Para um workspace ou ferramenta SaaS pronto para uso sem servidor para hospedar, use um Serviço MCP fornecido pela Databricks.

Requisitos

• Um workspace habilitado para o Unity Catalog.

• Um servidor MCP que pode ser acessado a partir do plano de compute serverless do seu workspace, seja pela internet ou por meio de conectividade privada. Se o workspace usar uma política de rede serverless no modo de acesso restrito, o nome de domínio totalmente qualificado do servidor deve ser um destino permitido nessa política. Consulte Rede.

• Um workspace em uma região onde o Model Serving é compatível. Consulte disponibilidade de recursos de serviço de modelo.

Registro de um servidor MCP externo

Registre seu próprio servidor MCP externo como um Serviço MCP em cinco passos:

1. Crie uma conexão do Unity Catalog com o servidor MCP.
2. Crie o serviço MCP dessa conexão.
3. Autentique-se, se a conexão usar OAuth por usuário.
4. Conceda acesso a seus colegas de equipe.
5. Invoque o serviço, então governe-o com seleção de ferramentas e políticas de serviço.

O servidor MCP externo deve usar o mecanismo de transporte HTTP streaming. São necessárias as seguintes permissões:

• Para criar a conexão , CREATE CONNECTION no esquema onde a criar.
• Para criar um serviço MCP, USE CATALOG e USE SCHEMA no catálogo e esquema pai, CREATE SERVICE no esquema e USE CONNECTION na conexão que o serviço MCP referencia.
• Para invocar um serviço MCP, EXECUTE no serviço MCP, USE CATALOG e USE SCHEMA em seu catálogo e esquema pai, e atribuição ao workspace onde você emite a solicitação.

atenção

A invocação de um serviço MCP exige **nenhum privilégio na conexão subjacente** —EXECUTE no serviço MCP é suficiente. Não conceda USE CONNECTION aos usuários finais: isso permite que eles chamem o servidor externo diretamente pela conexão, ou façam o registro do seu próprio serviço MCP nele, ignorando a seleção de ferramentas, políticas de serviço e auditoria do seu serviço MCP. Reserve o acesso à conexão para autores de serviço e administradores.

Passo 1. Criar uma conexão

Um Serviço MCP faz referência a uma conexão HTTP do Unity Catalog que armazena com segurança o endpoint e as credenciais do servidor externo. O Databricks executa um proxy gerenciado à frente dele para lidar com a autenticação e o refresh de tokens, para que você não incorpore credenciais no seu agente ou código de cliente.

Crie a conexão no nível de esquema para que seja governada juntamente com o Serviço MCP. Você pode configurá-lo com antecedência com os passos abaixo, ou criar um enquanto você cria o Serviço MCP clicando em Criar nova conexão . As conexões em nível de metastore são suportadas, mas não recomendadas.

Escolha uma das duas maneiras:

Create an HTTP connection

Para qualquer servidor MCP, incluindo servidores próprios ou de terceiros:

1. Vá para Catálogo > Conexões > Criar conexão .
2. Selecione **HTTP** como o tipo de conexão.
3. Digite a URL do servidor MCP.
4. Escolha um tipo de autenticação: bearer token, OAuth M2M, OAuth U2M ou Dynamic Client Registration. Para obter detalhes de configuração, consulte Crie uma conexão com o serviço externo.

Para provedores de OAuth gerenciados—Glean, GitHub, Atlassian e Slack—o Databricks gerencia as credenciais, então você não registra seu próprio aplicativo OAuth. Consulte Provedores de OAuth gerenciados.

Install from Marketplace

Use um servidor MCP selecionado do Databricks Marketplace com uma conexão pré-configurada. Consulte Obter acesso a servidores MCP externos.

Passo 2. Criar o serviço MCP

Você pode criar um serviço MCP a partir da interface do usuário ou com a API REST, a CLI do Databricks, os SDKs do Databricks ou o Terraform. DDL SQL para serviços MCP não é suportado.

UI

1. Em seu workspace Databricks, vá para AI Gateway > MCPs > Registro Servidor MCP , ou vá para Catálogo , selecione um esquema e clique em Criar > Serviço MCP .
2. Insira o catálogo, o esquema e um nome para o serviço MCP. O nome não pode ser alterado após a criação.
3. Selecione uma conexão HTTP existente para o servidor MCP, ou clique em **Criar nova conexão** para criar uma. Navegue sob um esquema para selecionar uma conexão em nível de esquema; para usar uma conexão em nível de metastore, desative **Navegar sob um esquema**.
4. Em **Ferramentas**, selecione quais ferramentas disponibilizar. Consulte Selecionar quais ferramentas são expostas.
5. Opcionalmente, adicione um comentário que descreva o Serviço MCP.
6. Clique em Criar . O Serviço MCP é publicado no catálogo e esquema que o senhor especificou.

REST API

Envie um POST para /api/2.1/Unity Catalog/mcp-serviços, passando parent e mcp_service_id como parâmetros de query. config.source_connection.name é a conexão HTTP do Unity Catalog que hospeda o servidor MCP. Para restringir quais ferramentas o serviço expõe, adicione uma lista de permissões include_tool_selectors; omita-a para expor todas as ferramentas. Consulte Selecione quais ferramentas são expostas.

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

Crie um serviço MCP que faça referência a uma conexão HTTP existente do Unity Catalog. Passe o esquema pai e um nome de folha, e forneça a configuração com --json. Para restringir quais ferramentas o serviço expõe, adicione uma lista de permissões include_tool_selectors; omita-a para expor todas as ferramentas. Para instalar a CLI, consulte Instalar ou atualizar a CLI do Databricks.

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

Crie e gerencie um serviço MCP com o provedor Databricks Terraform e o recurso databricks_ai_gateway_mcp_service:

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

Python SDK

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

Python

from databricks.sdk.service import catalog as c

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

Crie e gerencie um serviço 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",
			},
		},
	},
})

Java SDK

Crie e gerencie um serviço MCP com o Databricks SDK 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 SDK

Crie e gerencie um serviço MCP com o Databricks AI Gateway SDK for JavaScript:

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' },
      },
    },
  },
});

Etapa 3. Autenticar

Se o Serviço MCP referencia uma conexão que usa OAuth por usuário, conclua um login único antes da primeira chamada:

1. Abra a página de detalhes do serviço MCP no Catalog Explorer.
2. Clique em Fazer login e conclua o fluxo de consentimento OAuth do provedor.
3. Após o login, a página de detalhes exibe automaticamente a lista de ferramentas descobertas.

O Unity Catalog armazena os tokens associados à sua identidade. Se você chamar o Serviço MCP antes de fazer login, o AI Gateway retornará um erro solicitando que você se autentique.

nota

Usuários com Acesso do consumidor não podem usar o login OAuth por usuário, que requer Acesso ao Workspace . Consulte Gerenciar direitos.

Etapa 4. Conceder acesso a um serviço MCP

By default, apenas o proprietário do serviço MCP pode invocá-lo. Para permitir que outros invoquem um serviço MCP, conceda a eles EXECUTE nele, além de USE CATALOG e USE SCHEMA em seu catálogo e esquema. Uma única concessão EXECUTE cobre todas as ferramentas do serviço.

UI

1. Abra o serviço MCP no Catalog Explorer, ou vá para AI Gateway > MCPs e selecione o serviço.
2. Vá para a Permissões tab.
3. Clique em Conceder .
4. Selecione os usuários, grupos ou entidades de serviço aos quais conceder acesso.
5. Selecione o privilégio de EXECUÇÃO .
6. Clique em Conceder .

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. Para instalar a CLI, consulte Instalar ou atualizar a CLI do Databricks.

Bash

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

Terraform

Conceda EXECUTE com o provedor Databricks Terraform e o recurso databricks_grant:

Hcl

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

Python SDK

Conceda EXECUTE com o Databricks SDK 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

Conceda EXECUTE com o SDK do Databricks para 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)))));

O passo 5. Invocar um serviço MCP

Experimente um serviço MCP no AI Playground, da linha de comando, ou do código do seu agente ou cliente.

nota

Usuários com Acesso de consumidor podem invocar um serviço MCP compartilhado com eles, mas não podem registrar um serviço MCP. Consulte Gerenciar direitos.

Teste o serviço MCP

AI Playground

Teste as ferramentas de um serviço MCP na UI sem escrever código:

1. Acesse o AI Playground em seu workspace da Databricks.
2. Selecione um modelo com o rótulo Ferramentas ativadas .
3. Clique em Ferramentas > + Adicionar ferramenta e selecione Servidores MCP .
4. Selecione Servidores MCP externos e, em seguida, selecione o Serviço MCP.
5. Converse com o modelo para ver como ele chama as ferramentas do Serviço MCP.

Você também pode testar a partir do Genie Code. Consulte Adicionar servidores MCP ao Assistente.

CURL

Para uma verificação rápida da linha de comando, use os exemplos de solicitação na página de detalhes do serviço MCP em Comece . Os exemplos transmitem o token como um token do portador no cabeçalho Authorization.

Autentique a CLI do Databricks no seu workspace e, em seguida, use databricks auth token para obter um access token OAuth:

Bash

databricks auth login --host https://<workspace-url>

Todas as solicitações vão para o mesmo endpoint do Serviço MCP—o JSON-RPC method no corpo da solicitação seleciona a operação. Liste as ferramentas que o serviço expõe:

Bash

TOKEN=$(databricks auth token | jq -r .access_token)

curl -s -X POST \
  "https://<workspace-url>/ai-gateway/mcp-services/main.default.my_mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Chamar uma ferramenta:

Bash

curl -s -X POST \
  "https://<workspace-url>/ai-gateway/mcp-services/main.default.my_mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"<tool_name>","arguments":{'

Utilize a partir do código de agente ou de um agente de codificação

• Código do agente (OpenAI Agents SDK, LangGraph ou Model Serving): consulte Usar servidores MCP em agentes personalizados.
• Assistentes de AI e agentes de codificação (Claude, Claude Code, Cursor): consulte Conectar MCPs a assistentes de AI e agentes de codificação.

Gerenciar um serviço MCP

Atualizar um serviço MCP

Você deve ser um proprietário ou ter MANAGE.

UI

Edite a configuração do serviço MCP na IU do Unity Gateway ou no Catalog Explorer. As alterações são aplicadas no local.

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 reaplique. As alterações são aplicadas no local.

Python SDK

Python

from databricks.sdk.service import catalog as c
from google.protobuf.field_mask_pb2 import FieldMask

updated = w.ai_gateway.update_mcp_service(
    name="mcp-services/main.default.my_mcp",
    update_mask=FieldMask(paths=["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"},
})

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 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'),
});

Excluir um serviço MCP

Você deve ser um proprietário ou ter MANAGE.

UI

Abra o serviço MCP na interface do usuário do Unity Gateway ou no Catalog Explorer e selecione Excluir no menu kebab.

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

Execute terraform destroy ou remova o bloco de recursos e aplique novamente.

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

Java SDK

Java

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

JS SDK

TypeScript

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

Próximos os passos

• Governe um serviço MCP para restringir quais ferramentas o serviço expõe e aplique políticas de serviço.
• Conecte agentes a ferramentas com Serviços MCP para obter uma visão geral dos Serviços MCP e dos serviços fornecidos pela Databricks.
• Monitore toda a atividade de IA usando a tabela de rastreamento unificada para monitorar, depurar e auditar toda a atividade de MCP a partir de um único local.
• Governança de AI com o Unity Gateway para governar servidores MCP e LLM Endpoint a partir de um local central.