Héberger des serveurs MCP

Cette page explique où s'exécute un serveur MCP une fois utilisé par les agents d'un projet, comment la plateforme l'isole par projet, et comment le démarrer, l'arrêter, le mettre à jour et le supprimer. Elle s'adresse aux développeurs et aux administrateurs du tenant ; l'installation des services d'hébergement eux-mêmes relève des opérateurs et est liée en fin de page.

Trois façons d'héberger un serveur

La passerelle MCP du Control Plane n'atteint que des adresses internes (ADR-0170). Chaque serveur est donc hébergé à l'un de ces trois endroits.

Hébergement	Ce qui s'exécute	Qui l'exploite	Isolation	Entrée dans la passerelle
Hôte interne de l'entreprise	Un serveur MCP HTTP que l'entreprise développe et exécute	L'équipe propriétaire du serveur	L'hôte nommé dans EAI_MCP_INTERNAL_HOSTS (hôte exact, hôte:port, *.suffixe ou CIDR)	Enregistrée par POST /v1/mcp/servers, rattachée à un projet ou partagée par le tenant
Navin Manager, service mcp-host	Une commande stdio (npx, uvx) exposée en HTTP streamable	L'administrateur du tenant, depuis la page MCP du Navin Manager	Un processus enfant par serveur et par projet, environnement propre, dossier propre en mode 0700, jeton propre	Publiée par POST /v1/mcp/hosted/sync dans son projet
Runtime MCP (ToolHive Operator)	Une image de conteneur du catalogue MCP de l'entreprise	Chaque utilisateur, depuis le portail	Une instance par utilisateur, projet et modèle, dans un namespace par projet	Créée quand l'instance est prête, appelable par son propriétaire et ses agents uniquement

Le Runtime MCP est décrit dans Runtime MCP par utilisateur et par projet. Cette page couvre les deux premiers et les règles communes aux trois.

remarque

Un service MCP en ligne n'est jamais appelé. Un préréglage de la bibliothèque Navin marqué hosting: online (badge du portail "Service en ligne : adresse interne obligatoire") ne s'installe qu'avec l'adresse interne où l'entreprise l'héberge.

Isolation par projet

Un serveur rattaché à un projet n'est listé et appelé que depuis ce projet (ADR-0165) :

• Le projet d'une requête est l'en-tête X-Project, ou le projet auquel une clé d'API est liée.
• Depuis un autre projet, GET /v1/mcp/servers/{server_id}/tools, la découverte, le statut, le catalogue et la suppression répondent 403 mcp_server_project_mismatch, et la passerelle répond une erreur JSON-RPC avec le même code, sans appeler le serveur. Chaque refus est audité.
• Une requête sans contexte de projet est refusée (project_context_required), sauf pour tenant_admin et security_officer, qui gardent la vue de tous les projets.
• Un serveur sans projet est partagé par le tenant et visible depuis chaque projet.
• Dans un projet, PUT /v1/mcp/servers/{server_id}/access restreint les appelants à une liste d'utilisateurs et d'agents.

Requête	Serveurs listés par GET /v1/mcp/servers
Avec un contexte de projet	Les serveurs de ce projet et les serveurs partagés par le tenant
Avec ?project=<id-or-slug>	Les serveurs de ce projet uniquement (403 mcp_project_forbidden quand ce n'est pas le projet de la requête)
À l'échelle du tenant (tenant_admin, security_officer)	Tous les serveurs du tenant

Héberger un serveur sur un hôte interne

1. Déployer le serveur dans le réseau de l'entreprise. Utilisez le transport HTTP streamable ou SSE et une adresse dont l'opérateur liste l'hôte dans EAI_MCP_INTERNAL_HOSTS. Chaque adresse vers laquelle le nom se résout doit être privée : un nom qui se résout vers une adresse publique est refusé à la connexion.

   Résultat attendu : le serveur répond à initialize depuis le réseau du Control Plane.

   En cas d'échec : 403 mcp_online_forbidden à l'enregistrement ou à l'appel ; demandez à l'opérateur de lister l'hôte interne.

2. L'enregistrer dans son projet. Suivez le Guide de développement MCP : POST /v1/mcp/servers avec project et une référence d'identifiant openbao://.

   Résultat attendu : 201, le serveur est listé dans son projet uniquement.

   En cas d'échec : 403 mcp_project_forbidden quand le corps nomme un autre projet que celui de la requête.

3. Découvrir et approuver ses outils. POST /v1/mcp/servers/{server_id}/discover, puis approuvez les versions.

   Résultat attendu : GET /v1/mcp/catalog montre les outils approved.

   En cas d'échec : 502 upstream_error ; vérifiez que le serveur répond à tools/list.

Héberger un serveur stdio dans le Navin Manager

Le service mcp-host du Navin Manager (runtime navin-mcp-host, navin-manager/mcp-host) démarre chaque serveur stdio d'un projet dans son propre processus enfant, sans shell, avec des limites de mémoire, de fichiers et de core, l'arrête après sa durée d'inactivité et le redémarre après un plantage (en échec au-delà de 5 plantages par minute). Chaque serveur est exposé à /t/{tenant}/p/{project}/s/{name}/mcp avec son propre jeton ; l'hôte ne garde que l'empreinte sha256 du jeton et répond le même 401 à tout mauvais jeton. Il démarre les serveurs hors ligne (npm, uv et pip sans téléchargement).

1. Installer le service mcp-host (opérateur). L'opérateur l'installe depuis le catalogue du Navin Manager, en mode simple ou répliqué, et liste l'adresse de ses instances dans EAI_EGRESS_PRIVATE_ALLOWLIST du Control Plane. Voir Service d'hébergement MCP.

   Résultat attendu : les contrôles préalables (npx, uvx) passent et le service fonctionne.

   En cas d'échec : suivez le dépannage de la page du service.

2. Héberger le serveur du projet. Sur la page MCP du Navin Manager, choisissez le tenant, le projet et le préréglage ou la commande, saisissez les secrets (scellés par le Manager) et hébergez-le.

   Résultat attendu : le Manager écrit servers.json sur l'instance, le runtime le recharge et le serveur répond.

   En cas d'échec : le test de connexion de la page montre l'erreur du processus enfant.

3. Le publier dans le projet. Dans le portail, Bibliothèque Navin > MCP > Synchroniser les serveurs hébergés par le Navin Manager (tenant_admin), ou POST /v1/mcp/hosted/sync avec ?project=<slug>.

   client.mcp.sync_hosted(project="alpha")

   Résultat attendu : la réponse liste created, updated, disabled et skipped. Le jeton de chaque serveur est gardé dans le Credential Broker à openbao://mcp/hosted/<id>, jamais dans une table ni une réponse ; le serveur du projet reçoit une authentification bearer, ses outils autorisés et son hosted_ref.

   En cas d'échec : skipped donne une raison par entrée (other_tenant, invalid_id, invalid_name, invalid_url, token_missing, project_not_found, not_active, project_moved) ; 403 mcp_project_forbidden quand project diffère du projet de la requête.

4. Découvrir et approuver ses outils. Comme pour tout serveur.

   Résultat attendu : les agents du projet l'appellent par la passerelle.

   En cas d'échec : voir le Guide de développement MCP.

Cycle de vie

Opération	Hôte interne	Navin Manager (mcp-host)	Runtime MCP
Démarrer	L'équipe propriétaire démarre le serveur ; enregistrez-le une fois	Hébergez-le sur la page MCP du Manager, puis synchronisez	POST /v1/projects/{project_id}/mcp/instances, puis tout appel la réveille
Arrêter un temps	POST /v1/mcp/servers/{server_id}/status disabled (appliqué tout de suite, audité)	Retirez-le ou désactivez-le dans le Manager, puis synchronisez : le serveur est désactivé	POST /v1/projects/{project_id}/mcp/instances/{instance_id}/stop
Redémarrer	POST /v1/mcp/servers/{server_id}/status active (demande de promotion, 202)	Hébergez-le de nouveau, puis synchronisez : le serveur redevient active	POST /v1/projects/{project_id}/mcp/instances/{instance_id}/start, ou le prochain appel
Mettre à jour	Déployez le nouveau build à la même URL, puis relancez la découverte	Changez la commande ou la version dans le Manager (le processus redémarre, les sessions sont invalidées), synchronisez, relancez la découverte	Publiez une nouvelle image dans le catalogue de l'entreprise ; la génération suivante la prend
Renouveler l'identifiant	Écrivez le nouveau secret à la même référence openbao://	Menu "..." du Manager, renouvelez le jeton, puis synchronisez	Chaque génération reçoit de nouveaux identifiants
Supprimer	DELETE /v1/mcp/servers/{server_id} (tenant_admin)	Retirez-le dans le Manager, puis synchronisez (l'entrée est désactivée)	DELETE /v1/projects/{project_id}/mcp/instances/{instance_id}

attention

Désactiver un serveur coupe tous les agents du projet qui l'utilisent. Le réactiver passe par une demande de promotion qu'une seconde personne approuve.

Écrans et routes

Écran	Où	Routes
Studio MCP	Portail, studio/mcp	POST /v1/mcp/servers, POST /v1/mcp/servers/{server_id}/discover, GET /v1/mcp/catalog
Serveurs MCP	Portail, capabilities/mcp	GET /v1/mcp/servers, GET /v1/mcp/servers/{server_id}/tools, POST /v1/mcp/servers/{server_id}/status, DELETE /v1/mcp/servers/{server_id}, POST /v1/mcp/gateway/{server_id}
Bibliothèque Navin > MCP	Portail, studio/navin-library	POST /v1/projects/{project_id}/navin-library/mcp-presets/{name}/install, POST /v1/mcp/hosted/sync, PUT /v1/mcp/servers/{server_id}/access
Bibliothèque Navin > Instances MCP	Portail, studio/navin-library	GET /v1/projects/{project_id}/mcp/instances et les routes des instances
Page MCP	Navin Manager	Hébergement, renouvellement du jeton et test de connexion des serveurs stdio
Page du runtime MCP	Navin Manager	État de l'opérateur, instances, destruction et redémarrage

Vérifier

• GET /v1/mcp/servers envoyé avec le X-Project du projet liste le serveur ; envoyé avec un autre projet, il ne le liste pas.
• Un appel depuis un autre projet répond l'erreur JSON-RPC mcp_server_project_mismatch et l'audit contient le refus.

Étapes suivantes

• Runtime MCP par utilisateur et par projet
• Sécurité MCP
• Bibliothèque Navin

Dépannage

Symptôme	Cause	Correction
403 mcp_online_forbidden	Hôte public ou non listé comme interne	Hébergez le serveur en interne et listez son hôte
403 mcp_server_project_mismatch	Appel depuis un autre projet ou sans contexte de projet	Envoyez le X-Project du projet du serveur
La synchronisation répond skipped avec project_not_found	Le slug de projet du Manager n'existe pas dans le tenant	Créez le projet ou hébergez le serveur dans un projet existant
La synchronisation répond skipped avec project_moved	Le serveur hébergé a déjà été publié dans un autre projet	Retirez-le dans le Manager et hébergez-le de nouveau dans le bon projet
Serveur hébergé disabled après une synchronisation	Le Manager ne l'héberge plus	Hébergez-le de nouveau, puis synchronisez
409 mcp_preset_needs_endpoint à l'installation d'un préréglage	Préréglage stdio sans adresse HTTP	Hébergez-le dans le Navin Manager, puis donnez son URL ou synchronisez