Hébergez un serveur MCP sur Databricks Apps
Créez un serveur MCP sur Databricks Apps pour permettre à votre agent d'appeler vos propres outils. Databricks Apps fournit le compute pour exécuter le serveur ainsi qu'une URL HTTPS à laquelle les agents peuvent se connecter.
Choisissez votre chemin d'accès
Choisissez l'une de ces trois manières d'héberger un serveur MCP sur Databricks Apps :
- Build a server from the Starter template to write your own Python tools.
- Exposer une API REST en tant qu'outils MCP si vous disposez déjà d'une API HTTP.
- Deploy an existing MCP server si vous possédez déjà le code du serveur.
Créez un serveur à partir du template Starter
Le template MCP Server (Starter) inclut deux outils que vous pouvez appeler avant d'ajouter votre propre code Python : health, qui vérifie que le serveur est en cours d'exécution, et get_current_user, qui retourne l'identité de l'utilisateur appelant. get_current_user fonctionne uniquement lorsque l’application dispose de périmètres d’autorisation utilisateur.
Rechercher et déployer le Template
Utilisez un workspace qui répond aux exigences de Databricks Apps.
- Databricks UI
- Databricks CLI
- Dans votre workspace, ouvrez Unity Gateway et sélectionnez MCPs .
- Cliquez sur + MCP et choisissez Créer un nouveau serveur MCP . La page de création de Databricks Apps s’ouvre.
- Trouvez Installer à partir d’un template . Dans cette galerie de templates, sélectionnez le tab Agents , puis MCP Server (Starter) .
- Examinez les paramètres de Ressources, de compute et d'autorisation. Cliquez sur Next pour poursuivre la configuration.
- Nommez l’application
mcp-my-serveret cliquez sur Create app . Utilisez un autre nom commençant parmcp-si ce nom est déjà pris. Ce préfixe permet à AI Playground de reconnaître le serveur MCP.
-
Connectez-vous à votre workspace avec Databricks CLI.
-
Clonez la source du template depuis
databricks/app-templates/mcp-server-hello-world:Bashgit clone https://github.com/databricks/app-templates.gitcd app-templates/mcp-server-hello-world -
Créez l’application. Utilisez un autre nom commençant par
mcp-simcp-my-serverest déjà utilisé. Ce préfixe permet à AI Playground de reconnaître le serveur MCP.Bashdatabricks apps create mcp-my-server -
upload le code du Template dans votre Workspace. Remplacez
<your-email>par votre nom d’utilisateur Workspace.Bashdatabricks sync . /Workspace/Users/<your-email>/mcp-my-server -
Déployez l’application à partir du dossier upload :
Bashdatabricks apps deploy mcp-my-server --source-code-path /Workspace/Users/<your-email>/mcp-my-server -
Obtenez l’URL de l’application à partir du champ
urlde la sortie :Bashdatabricks apps get mcp-my-server
Dans l’UI, la création d’une application à partir du template déploie également le code du template. Avec le CLI, databricks apps create crée l’application sans déployer le code ; exécutez donc databricks apps deploy avec --source-code-path comme indiqué. Attendez la fin du déploiement. La page Vue d’ensemble de l’application affiche son URL et son statut de déploiement.
Appeler le premier outil
Copiez l'URL de l'application depuis sa page Overview et ajoutez /mcp à la suite :
https://<app-hostname>/mcp
Connectez votre agent avec cette URL.
Demandez à votre agent : "Appelle l'outil de santé." Confirmez que l'outil retourne "status": "healthy". Pour vérifier le serveur sans agent, consultez Appeler un outil depuis Python.
Si get_current_user échoue lors de son appel par votre agent, consultez Dépannage.
Ajoutez votre propre outil
Ajoutez un outil qui convertit le texte en majuscules :
-
Obtenez le code source. Si vous avez effectué le déploiement avec la CLI, utilisez votre clone du template. Sinon, sur la page Aperçu de l'application, suivez Modifier dans votre IDE pour copier le code source sur votre informatique et synchroniser les modifications sur le workspace.
-
Ouvrez
server/tools.py. Ajoutez cette fonction à l'intérieur deload_tools(mcp_server), aux côtés des outils existants :Python@mcp_server.tooldef uppercase(text: str) -> str:"""Convert a string to uppercase."""return text.upper() -
Synchronisez vos modifications et redéployez l’application. Avec CLI, exécutez ceci à partir du dossier template :
Bashdatabricks sync . /Workspace/Users/<your-email>/mcp-my-server && databricks apps deploy mcp-my-server --source-code-path /Workspace/Users/<your-email>/mcp-my-server -
Reconnectez votre agent pour charger les outils mis à jour. Demandez-lui d’appeler
uppercaseavechelloet confirmez que le résultat estHELLO.
Consultez la source du Template de démarrage pour obtenir le serveur complet.
Expose a REST API as MCP tools
Utilisez cette option lorsque vous disposez déjà d’une HTTP API, telle qu’une API de recherche de clients, et que vous souhaitez que votre agent l’appelle. Le Template MCP Server (OpenAPI) fournit des outils pour découvrir et appeler les Endpoint de votre API.
Préparer l’API
Le template a besoin de deux choses :
- An API description: Save your API's OpenAPI 3.x specification as
spec.jsonand upload it to a volume. Place it at the volume root, outside any subfolder. See the example specification. - Une connexion HTTP : Créez une connexion qui stocke les identifiants d'authentification de votre API, ou utilisez une connexion existante. Stockez le jeton backend ou les identifiants client OAuth dans cette connexion. Copiez le nom de la connexion. En créer un nécessite
CREATE CONNECTION.
Choisissez la méthode d’authentification de la connexion pour l’identité que votre API doit recevoir :
- Compte fournisseur de chaque utilisateur : choisissez OAuth User-to-Machine Per User et configurez les paramètres OAuth du fournisseur.
- Un compte partagé : Choisissez jeton Bearer , OAuth machine à machine ou OAuth utilisateur vers machine partagé , selon ce que l’API prend en charge.
Voir les méthodes d'authentification de connexion HTTP pour les options prises en charge et les propriétés de connexion pour les identifiants requis et les Endpoint OAuth.
Créer l’application
- Dans Unity Gateway , sélectionnez MCPs , cliquez sur + MCP , puis choisissez Build a new MCP server .
- Sur la page de création des applications, sous Install from a template , sélectionnez Agents , puis MCP Server (OpenAPI) .
- Pour la ressource uc-volume , sélectionnez le volume contenant
spec.json. Cela donne à l’application accès à la description de votre API. - Poursuivez avec les paramètres de compute et d’autorisation. Nommez l’application
mcp-my-apiet cliquez sur Créer une application .
Configurer l’authentification et la connexion
Le Template utilise le jeton Databricks de l’appelant pour accéder à la connexion HTTP. La connexion fournit les informations d’identification de l’API externe. Cela s’applique même lorsque tous les appelants utilisent un compte backend partagé.
-
Dans le cadre de l'autorisation utilisateur, vérifiez que l'application demande
catalog.connections, la portée déclarée par le template. -
Accorder à chaque appelant CAN USE sur l’application et
USE CONNECTIONsur la connexion HTTP. Pour accorder un accès à la connexion, ouvrez Catalogue > Connexions , sélectionnez la connexion et utilisez son tab Autorisations . -
Sur la page Overview de l'application, utilisez Edit in your IDE pour copier le code source sur votre ordinateur et configurer la synchronisation avec le workspace.
-
Ouvrez
app.yaml. Dans la sectionenv, recherchezUC_CONNECTION_NAMEet définissez sa valeur sur le nom de votre connexion :YAML- name: UC_CONNECTION_NAMEvalue: my_api_connectionRemplacez
my_api_connectionpar le nom de votre connexion. Laissez les autres paramètres de template inchangés. -
Synchronisez le fichier mis à jour, puis redéployez l'application. Attendez que le déploiement se termine dans Aperçu .
Effectuer le premier appel
Connectez-vous avec un jeton OAuth Databricks qui inclut les étendues d’autorisation de l’utilisateur de l’application. Voir Étendues OAuth pour les appels d’applications. Pour une connexion par utilisateur, chaque appelant doit également autoriser son compte de fournisseur en utilisant le flux de connexion OAuth de la connexion HTTP.
- Copiez l'URL de l'application depuis Overview , ajoutez
/mcpet connectez votre agent. - Demandez à votre agent d’appeler
list_api_endpoints. Vérifiez que le résultat inclut les Endpoint dans votre spécification. - Demandez à l’agent d’appeler un endpoint en lecture seule et confirmez qu’il renvoie des données de votre API.
Le template lit le jeton utilisateur à partir de x-forwarded-access-token et appelle serving_endpoints.http_request avec le nom de connexion. Voir l’ assistant d’authentification et le gestionnaire de requêtes d’API.
Pour tout nouveau code qui appelle l’API en dehors de ce Template, Databricks recommande d’utiliser le proxy de connexion HTTP.
Exemple de spécification OpenAPI
Cette spécification décrit GET /widgets. Remplacez l'URL et les Opérations par les valeurs de votre API :
{
"openapi": "3.1.0",
"info": { "title": "Example API", "version": "1.0.0" },
"servers": [{ "url": "https://api.example.com" }],
"paths": {
"/widgets": {
"get": {
"summary": "List widgets",
"responses": { "200": { "description": "A list of widgets" } }
}
}
}
}
Déployer un serveur MCP existant
Hébergez votre serveur MCP existant sur Databricks Apps.
Préparer votre serveur
Votre dossier source doit contenir les éléments suivants :
-
Un serveur HTTP : configurez HTTP diffusable. Écoutez sur
0.0.0.0et sur le port dansDATABRICKS_APP_PORT(default8000). Notez votre chemin MCP, tel que/mcp. -
Dépendances : incluez le fichier de dépendance approprié, tel que
requirements.txtpour Python oupackage.jsonpour Node.js. -
Commande start : ajoutez
app.yamlavec la commande qui démarre votre serveur. Pour un point d'entrée Python nomméserver.py, utilisez :YAMLcommand: ['python', 'server.py']
Déployer et connecter
- Dans Unity Gateway , sélectionnez MCPs , cliquez sur + MCP , puis choisissez Build a new MCP server .
- Sur la page de création d'applications, choisissez Create a custom app . Nommez-le avec le préfixe
mcp-et terminez la configuration de l'application. - Sur la page Overview de l'application, utilisez Edit in your IDE pour synchroniser votre dossier source avec le workspace.
- Cliquez sur Deploy , sélectionnez le dossier du workspace, puis cliquez sur Select et Deploy . Attendez la fin du déploiement. Consultez Instructions de déploiement.
- Copiez l'URL de l'application et ajoutez votre chemin MCP. Connectez votre agent à l'aide de cette URL et appelez l'un des outils de votre serveur pour vérifier la connexion.
Connectez votre agent
Utilisez l'URL MCP correspondant au chemin d'accès que vous avez choisi. Pour les Template de démarrage et OpenAPI, ajoutez /mcp à l'URL de l'application. Pour un serveur existant, utilisez le chemin MCP configuré dans votre serveur.
Choisissez le guide de configuration de votre agent :
- Agents de codage : utilisez
ug, la Unity Gateway CLI. Installez-la et configurez-la, puis ajoutez l'application avecug mcp add --names "app:mcp-my-server", en remplaçantmcp-my-serverpar le nom de votre application.ugécrit la connexion dans la configuration de votre agent de codage, de sorte que la propre CLI de l'agent doit être installée, configurée et sur votrePATH. Les agents pris en charge incluent Claude Code, Codex et Cursor. Voir Agents de codage et de travail pris en charge. - Python agents: Follow Use MCP tools with the app's MCP URL.
- Autres clients : Enregistrez un client OAuth avec l’URL de redirection du client et les scopes d’autorisation utilisateur de l’application. Configurez le client avec l’URL MCP de votre application.
Les appelants doivent disposer de CAN USE sur l'application et d'un jeton OAuth. Les jetons d'accès personnel ne sont pas pris en charge. Voir Autorisations des applications et authentification par jeton pour les applications.
Appeler un outil à partir de Python
Pour tester le serveur sans agent, appelez health avec la version 2 du SDK Python MCP:
pip install --upgrade "mcp>=2"
Obtenez un jeton OAuth avec databricks auth token et copiez sa valeur access_token. Un jeton du Databricks CLI inclut la portée all-apis, qui couvre les portées d'autorisation utilisateur de toute application. Voir l'authentification par jeton pour les applications. Ensuite, ouvrez une session vers l’URL MCP de l’application et appelez l’outil :
import asyncio
import httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
MCP_URL = "https://<app-hostname>/mcp"
async def main(databricks_token):
http_client = httpx2.AsyncClient(headers={"Authorization": f"Bearer {databricks_token}"})
async with http_client, streamable_http_client(MCP_URL, http_client=http_client) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.list_tools()
print([tool.name for tool in result.tools])
result = await session.call_tool("health", arguments={})
print(result)
asyncio.run(main("<oauth-token>"))
Le résultat health inclut "status": "healthy".
Dépannage
get_current_userrenvoieAuthentication token not found in request headers (x-forwarded-access-token). L’application manque de périmètres d’autorisation utilisateur. Ajoutez des périmètres à l’application, puis connectez-vous avec un jeton OAuth qui les inclut. Consultez l’authentification par jeton pour les apps.
Tarifs et monitoring
Les applications utilisent les Tarifs de Databricks Apps. Pour les logs de déploiement et de requête, consultez Journaux et monitoring pour Databricks Apps.