Enregistrer un serveur MCP externe

Cette page explique comment enregistrer un serveur MCP auto-hébergé ou tiers en tant que service MCP dans Unity Catalog, puis l'invoquer depuis AI Playground, la ligne de commande ou votre code d'agent. Enregistrer le serveur en tant qu'élément sécurisable de Unity Catalog permet à la Unity AI Gateway de proxifier chaque appel avec des identifiants gérés, afin que les agents ne gèrent jamais les jetons du serveur. Pour restreindre les outils que le service expose et gérer les appels individuels, consultez Gérer un service MCP.

Pour un outil SaaS prêt à l'emploi sans serveur à héberger, utilisez plutôt un service MCP fourni par Databricks.

Exigences

• Un workspace activé pour Unity Catalog.

• Un workspace dans une région où Model Serving est pris en charge. Voir la disponibilité des fonctionnalités de Model Serving.

Enregistrer un serveur MCP externe

Enregistrez votre propre serveur MCP externe en tant que service MCP en cinq étapes :

1. Créer une connexion Unity Catalog au serveur MCP.
2. Créez le service MCP à partir de cette connexion.
3. Authentifiez-vous, si la connexion utilise OAuth par utilisateur.
4. Accorder l'accès à vos coéquipiers.
5. Invoquez le service, puis gouvernez-le avec la sélection d'outils et les politiques de service.

Le serveur MCP externe doit utiliser le mécanisme de transport HTTP diffusable. Vous avez besoin de ces autorisations :

• Pour créer la connexion , CREATE CONNECTION sur le schéma où vous la créez.
• Pour créer un service MCP, USE CATALOG et USE SCHEMA sur le catalogue et le schéma parents, CREATE SERVICE sur le schéma et USE CONNECTION sur la connexion que le service MCP référence.
• Pour invoquer un service MCP, EXECUTE sur le service MCP, USE CATALOG et USE SCHEMA sur son catalogue et schéma parents, et une affectation au Workspace où vous émettez la demande.

attention

L'invocation d'un service MCP ne nécessite **aucun privilège sur la connexion sous-jacente** —EXECUTE sur le service MCP est suffisant. Ne donnez pas USE CONNECTION aux utilisateurs finaux : cela leur permet d'appeler directement le serveur externe via la connexion, ou d'enregistrer leur propre service MCP dessus, contournant la sélection d'outils, les politiques de service et l'audit de votre service MCP. Réservez l'accès à la connexion pour les auteurs de services et les administrateurs.

Étape 1. Créer une connexion

Un service MCP fait référence à une connexion HTTP de Unity Catalog qui stocke en toute sécurité l'Endpoint et les identifiants du serveur externe. Databricks exécute un proxy géré en amont pour gérer l'authentification et le refresh des jetons, de sorte que vous n'ayez pas à intégrer les identifiants dans votre agent ou votre code client.

Créez la connexion au niveau du schéma afin qu'elle soit régie en même temps que le service MCP. Vous pouvez le configurer à l'avance en suivant les étapes ci-dessous, ou en créer un en cliquant sur Créer une nouvelle connexion pendant que vous créez le service MCP. Les connexions au niveau du métastore sont prises en charge mais non recommandées.

Choisissez l'une des deux modalités :

Create an HTTP connection

Pour tout serveur MCP, y compris les serveurs auto-hébergés ou tiers :

1. Accédez à **Catalogue** > **Connexions** > **Créer une connexion**.
2. Sélectionnez HTTP comme type de connexion.
3. Saisissez l'URL du serveur MCP.
4. Choisissez un type d'authentification : jeton du porteur, OAuth M2M, OAuth U2M ou enregistrement dynamique du client. Pour les détails de configuration, consultez Créer une connexion au service externe.

Pour les fournisseurs OAuth gérés — Glean, GitHub, Atlassian et Slack —, Databricks gère les informations d'identification, vous n'avez donc pas besoin d'enregistrer votre propre application OAuth. Voir Fournisseurs OAuth gérés.

Install from Marketplace

Utilisez un serveur MCP géré depuis Databricks Marketplace avec une connexion préconfigurée. Voir Accéder aux serveurs MCP externes.

Étape 2 : créez le service MCP

Vous pouvez créer un service MCP à partir de l’interface utilisateur ou avec l’API REST, la CLI Databricks, les SDK Databricks ou Terraform. Le DDL SQL pour les services MCP n’est pas pris en charge.

UI

1. Dans votre Workspace Databricks, accédez à Passerelle IA > MCP > Enregistrer le serveur MCP , ou accédez au Catalogue , sélectionnez un schéma et cliquez sur Créer > Service MCP .
2. Saisissez le catalogue, le schéma et un nom pour le service MCP. Le nom ne peut pas être changé après la création.
3. Sélectionnez une connexion HTTP existante au serveur MCP, ou cliquez sur Créer une nouvelle connexion pour en créer une. Parcourez un schéma pour sélectionner une connexion au niveau du schéma ; pour utiliser une connexion au niveau du metastore, désactivez Parcourir sous un schéma .
4. Sous Outils , sélectionnez les outils à rendre disponibles. Consultez Sélectionnez les outils exposés.
5. Vous pouvez éventuellement ajouter un commentaire décrivant le service MCP.
6. Cliquez sur Créer. Le service MCP est publié dans le catalogue et le schéma que vous avez spécifiés.

REST API

Envoyez un POST à /api/2.1/unity-catalog/mcp-services, transmission de parent et mcp_service_id en tant que parameters de query. config.source_connection.name est la connexion HTTP Unity Catalog qui héberge le serveur MCP. Pour restreindre les outils exposés par le service, ajoutez une liste d'autorisation include_tool_selectors ; omettez-la pour exposer tous les outils. Voir Sélectionner les outils exposés.

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

Créez un service MCP qui référence une connexion HTTP Unity Catalog existante. Transmettez le schéma parent et un nom de feuille, et fournissez la configuration avec --json. Pour restreindre les outils exposés par le service, ajoutez une liste d’autorisation include_tool_selectors ; omettez-la pour exposer tous les outils. Pour installer la CLI, consultez Installer ou mettre à jour la CLI 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

Créez et gérez un service MCP avec le fournisseur Databricks Terraform et la ressource 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

Créez et gérez un service MCP avec le SDK Databricks pour 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

Créez et gérez un service MCP avec le Databricks SDK for 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

Créez et gérez un service MCP avec le Databricks SDK for 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

Créez et gérez un service MCP avec le SDK Databricks AI Gateway pour 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' },
      },
    },
  },
});

Étape 3. Authentifiez-vous

Si le service MCP fait référence à une connexion qui utilise OAuth par utilisateur, effectuez une connexion unique avant le premier appel :

1. Ouvrir la page de détails du service MCP dans l'Explorateur de catalogues.
2. Cliquez sur Connexion et effectuez le flux de consentement OAuth du fournisseur.
3. Après vous être connecté, la page détaillée affiche automatiquement la liste des outils découverts.

Unity Catalog stocke le jeton par rapport à votre identité. Si vous appelez le service MCP avant de vous connecter, AI Gateway renvoie une erreur vous invitant à vous authentifier.

remarque

Les utilisateurs disposant d'un accès consommateur ne peuvent pas utiliser la connexion OAuth par utilisateur, qui nécessite un accès Workspace . Voir Gérer les droits.

Étape 4. Accorder l'accès à un service MCP

Par default, seul le propriétaire du service MCP peut l’invoquer. Pour permettre à d’autres personnes d’invoquer un service MCP, accordez-leur EXECUTE sur celui-ci, ainsi que USE CATALOG et USE SCHEMA sur son catalogue et son schéma. Une seule autorisation EXECUTE couvre tous les outils du service.

UI

1. Ouvrez le service MCP dans l'explorateur de catalogues, ou accédez à AI Gateway > MCPs et sélectionnez le service.
2. Allez à l'onglet Autorisations .
3. Cliquez sur Accorder .
4. Sélectionnez les utilisateurs, les groupes ou les Service Principal auxquels accorder l'accès.
5. Sélectionnez le privilège **EXECUTE**.
6. Cliquez sur Accorder .

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

Étape 5. Invoquez un service MCP.

Essayez un service MCP dans AI Playground, depuis la ligne de commande, ou à partir de votre code d'agent ou de client.

remarque

Les utilisateurs disposant d’un accès consommateur peuvent appeler un service MCP partagé avec eux, mais ne peuvent pas enregistrer de service MCP. Voir Gérer les droits.

Tester le Service MCP

AI Playground

Tester les outils d'un service MCP dans l'UI sans écrire de code :

1. Accédez à AI Playground dans votre workspace Databricks.
2. Sélectionnez un modèle avec le libellé **Outils activés**.
3. Cliquez sur Outils > + Ajouter un outil et sélectionnez Serveurs MCP .
4. Sélectionnez Serveurs MCP externes , puis sélectionnez le service MCP.
5. Discutez avec le modèle pour voir comment il appelle les outils du service MCP.

Vous pouvez également tester à partir de Genie Code — voir Ajouter des serveurs MCP à l'Assistant.

CURL

Pour une vérification rapide en ligne de commande, utilisez les exemples de requête sur la page de détails du service MCP sous Get started . Les exemples transmettent le jeton en tant que jeton Bearer dans l'en-tête Authorization.

Authentifiez la CLI Databricks auprès de votre workspace, puis utilisez databricks auth token pour obtenir un jeton d’accès OAuth :

Bash

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

Toutes les requêtes vont au même Endpoint du service MCP : le JSON-RPC method dans le corps de la requête sélectionne l'opération. Lister les outils que le service expose :

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

Appeler un outil :

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":{'

Utiliser à partir de code d'agent ou d'un agent de codage

• Code d'agent (OpenAI Agents SDK, LangGraph ou Model Serving) : voir Utiliser des serveurs MCP dans des agents personnalisés.
• Assistants IA et agents de codage (Claude, Claude Code, Cursor) : voir Connecter les MCP aux assistants IA et aux agents de codage.

Gérer un service MCP

Mettre à jour un service MCP

Vous devez être propriétaire ou disposer de MANAGE.

UI

Modifiez la configuration du service MCP depuis l’interface utilisateur de Unity AI Gateway ou depuis Catalog Explorer. Les modifications s’appliquent sur place.

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

Modifiez comment (ou tout autre champ mutable) sur la ressource databricks_ai_gateway_mcp_service et réappliquez. Les modifications s’appliquent sur place.

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

Supprimer un service MCP

Vous devez être propriétaire ou disposer de MANAGE.

UI

Ouvrez le service MCP dans l’interface utilisateur de Unity AI Gateway ou dans Catalog Explorer, puis sélectionnez Delete dans le 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

Exécutez terraform destroy, ou supprimez le bloc de ressources et réappliquez.

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

Étapes suivantes

• Gouvernez un service MCP afin de restreindre les outils que le service expose et d'appliquer les politiques de service.
• Connecter des agents à des outils tiers avec les services MCP pour un aperçu des services MCP et des services fournis par Databricks.
• Supervisez toute l'activité IA à l'aide de la table de trace unifiée pour surveiller, déboguer et auditer toute l'activité MCP depuis un seul endroit.
• Gouvernance de l'IA avec Unity AI Gateway pour gouverner les serveurs MCP et les Endpoint LLM depuis un emplacement central.