Serveur MCP

Ce que fait le serveur MCP

Le serveur MCP de BaaStide donne des outils à un client MCP, par exemple un assistant IA. Le client lit l'état des sauvegardes, lance des sauvegardes et des restaurations, et enrôle des machines. Chaque appel porte le jeton d'un utilisateur. Le serveur MCP n'a aucun identifiant qui lui est propre.

Le serveur MCP n'atteint qu'un seul MSP : celui du jeton. Il ne rend jamais le contenu d'une sauvegarde.

Cette page décrit le protocole, pour écrire ou régler un client MCP. Pour connecter un assistant IA déjà fait, lisez Utiliser un assistant IA.

Prérequis

• L'adresse du portail BaaStide qui vous sert.
• Un administrateur de la plateforme a configuré le serveur MCP de l'instance.
• Un administrateur du MSP a activé l'accès MCP du MSP. Voir Accès MCP.
• Un compte d'utilisateur actif dans ce MSP. Son rôle fixe ce que le client MCP peut faire.
• Un client qui parle MCP sur HTTP, avec OAuth 2.1 et PKCE.

Trouver l'adresse du serveur MCP

1. Connectez-vous au portail avec le rôle Administrateur.
2. Dans la barre du haut, cliquez sur Administration.
3. Cliquez sur Accès MCP.
4. Lisez le champ URL du serveur MCP.

L'adresse est le chemin /mcp de l'hôte du portail, par exemple https://backup.example.com/mcp. Elle sert aussi d'audience (resource) de chaque jeton.

Si la page affiche L'accès MCP n'est pas configuré, l'administrateur de la plateforme doit d'abord configurer le serveur MCP de l'instance.

Lire les documents de découverte

Deux documents décrivent le serveur MCP et son serveur d'autorisation. Ils sont publics et ne demandent aucun jeton.

1. Appelez GET https://<portail>/.well-known/oauth-protected-resource. La réponse donne resource (l'adresse du serveur MCP), authorization_servers, scopes_supported, bearer_methods_supported et resource_name.
2. Appelez GET https://<portail>/.well-known/oauth-authorization-server. La réponse donne l'émetteur et les adresses des points d'entrée OAuth.

Le premier document répond aussi sous le chemin du serveur MCP, par exemple /.well-known/oauth-protected-resource/mcp.

Le tableau donne les points d'entrée OAuth du serveur d'autorisation.

Chemin	Usage
POST /api/oauth/register	Enregistrer un client (RFC 7591).
GET /api/oauth/authorize	Demander une autorisation.
POST /api/oauth/token	Échanger un code, ou rafraîchir un jeton.
POST /api/oauth/revoke	Révoquer un jeton (RFC 7009).

Le serveur d'autorisation accepte seulement :

• la réponse code ;
• les types authorization_code et refresh_token ;
• PKCE avec la méthode S256. La méthode plain est refusée ;
• les méthodes d'authentification none, client_secret_post et client_secret_basic.

Il renvoie le paramètre iss avec la réponse d'autorisation (RFC 9207).

Enregistrer son client

Un client s'enregistre lui-même. Aucune action du portail n'est nécessaire.

1. Envoyez POST https://<portail>/api/oauth/register avec un corps JSON.
2. Mettez dans redirect_uris de 1 à 10 adresses de retour. Chaque adresse est en https, ou en http sur localhost, 127.0.0.1 ou [::1]. Une adresse ne porte ni fragment ni identifiant d'utilisateur.
3. Ajoutez client_name pour que le nom de votre application s'affiche dans le portail.
4. Pour un client confidentiel, ajoutez token_endpoint_auth_method avec la valeur client_secret_post ou client_secret_basic. Sans ce champ, le client est public et n'a pas de secret.
5. Lisez la réponse 201. Elle donne client_id, les adresses de retour enregistrées et les méthodes acceptées.

POST /api/oauth/register HTTP/1.1
Host: backup.example.com
Content-Type: application/json

{"client_name": "Mon outil", "redirect_uris": ["https://outil.example.com/callback"]}

Un client confidentiel reçoit client_secret dans cette réponse, une seule fois. Le champ client_secret_expires_at vaut 0 : le secret n'expire pas. Gardez-le dans un coffre à secrets.

L'enregistrement est limité par adresse IP : une réserve de 30 enregistrements, puis 30 par heure. Au-dessus, la réponse est 429 avec le code invalid_request.

Obtenir un jeton d'accès

Le serveur suit le flux du code d'autorisation avec PKCE.

1. Tirez un code_verifier de 43 à 128 caractères. Calculez son empreinte SHA-256 en base64url : c'est le code_challenge.
2. Ouvrez un navigateur sur GET https://<portail>/api/oauth/authorize avec les paramètres response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256, scope, state et resource.
3. Le serveur vérifie la demande, puis envoie le navigateur sur la page de consentement du portail.
4. L'utilisateur se connecte, choisit son MSP et ses portées, puis clique sur Autoriser l'accès.
5. Le navigateur revient sur votre redirect_uri, avec code, state et iss.
6. Envoyez POST https://<portail>/api/oauth/token avec un corps de formulaire : grant_type=authorization_code, code, code_verifier, redirect_uri et client_id.
7. Lisez la réponse. Elle donne access_token, token_type, expires_in, refresh_token et scope.

POST /api/oauth/token HTTP/1.1
Host: backup.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&code_verifier=...&client_id=...

Règles de ces deux appels :

• redirect_uri doit être une des adresses enregistrées, caractère pour caractère. Un préfixe ou un motif est refusé. Un client qui a enregistré une seule adresse peut omettre le paramètre.
• scope est une liste séparée par des espaces. La portée read est toujours ajoutée. Une portée inconnue donne l'erreur invalid_scope.
• resource doit être l'adresse du serveur MCP. Une barre oblique finale est ignorée. Une autre valeur donne l'erreur invalid_target. Sans ce paramètre, le serveur prend l'adresse du serveur MCP.
• state tient au plus 1 024 caractères.
• Une erreur de GET /api/oauth/authorize est toujours une réponse 400, jamais une redirection. Le corps donne error et error_description.
• Un client public n'envoie aucun secret. Un client confidentiel envoie son secret dans le corps, ou dans un en-tête Authorization: Basic.
• Un refus de l'utilisateur ramène le navigateur sur votre redirect_uri avec error=access_denied, state et iss.

Un jeton d'accès commence par bst_at_. Un jeton de rafraîchissement commence par bst_rt_.

Rafraîchir et révoquer un jeton

1. Envoyez POST https://<portail>/api/oauth/token avec grant_type=refresh_token, refresh_token et client_id.
2. Lisez la réponse. Elle donne un nouveau jeton d'accès et un nouveau jeton de rafraîchissement.
3. Remplacez les deux jetons chez vous. L'ancien jeton de rafraîchissement ne sert plus.

Pour rendre un accès avant son terme, envoyez POST https://<portail>/api/oauth/revoke avec le champ token. La réponse est toujours 200, même pour un jeton inconnu.

• Un jeton de rafraîchissement révoqué met fin à tout l'accès.
• Un jeton d'accès révoqué s'arrête seul.
• Le paramètre scope d'un rafraîchissement peut réduire les portées. Il ne peut jamais les élargir.

Appeler un outil

1. Envoyez POST sur l'adresse du serveur MCP.
2. Ajoutez l'en-tête Authorization: Bearer <jeton d'accès>.
3. Ajoutez l'en-tête Content-Type: application/json et un corps JSON-RPC.
4. Appelez initialize, puis tools/list, puis tools/call.

Le serveur MCP parle HTTP en flux (Streamable HTTP), sans session. Un POST est un échange complet. Les méthodes GET et DELETE sur ce chemin répondent 405.

Le serveur ne liste que les outils des portées du jeton. Un jeton absent, d'un autre format ou refusé donne 401, avec un en-tête WWW-Authenticate qui porte l'adresse du document de découverte.

La liste complète des outils est dans Outils MCP.

Portées

Portée	Ce qu'elle permet	Droit du rôle
read	Lire l'état des sauvegardes. Toujours présente.	Lecture
operate	Modifier les politiques, lancer et annuler des sauvegardes, lancer des restaurations, lancer un export PST.	Opération
enroll	Créer un client, créer et révoquer un jeton d'enrôlement de machine.	Opération

À chaque appel, le droit est l'intersection des portées du jeton et des droits du rôle que l'utilisateur a maintenant dans le MSP. Un changement de rôle s'applique tout de suite.

Lister et chercher les noms, chemins, tailles et dates des fichiers d'un point de restauration demande la portée read, et en plus le droit d'opération du rôle, comme dans le portail. Un rôle Lecture seule reçoit 403. Ces deux routes ne rendent jamais le contenu d'un fichier.

La portée enroll demande en plus que l'administrateur du MSP garde l'option ouverte. Dès qu'il la ferme, chaque jeton perd cette portée. Un accès déjà donné ne gagne jamais une portée : ses portées sont fixées au consentement, et un rafraîchissement ne les élargit pas.

Un administrateur de la plateforme n'obtient par MCP que ses appartenances à un MSP. La portée de la plateforme n'est jamais donnée.

Limites et précautions

• Durées : un code vaut 5 minutes et sert une seule fois ; un jeton d'accès vaut 15 minutes ; un jeton de rafraîchissement vaut 30 jours et sert une seule fois.
• Un code réutilisé, ou un jeton de rafraîchissement réutilisé après sa rotation, révoque tout l'accès. Ne gardez jamais deux copies d'un jeton de rafraîchissement.
• Un corps de requête tient au plus 256 Kio. Au-dessus, la réponse est 413. Une requête sans en-tête Content-Length reçoit 411.
• Limites de débit par défaut : 300 requêtes par minute et par jeton, 600 requêtes par minute et par adresse IP. Un dépassement donne 429 avec l'en-tête Retry-After. L'administrateur de la plateforme peut changer ces deux valeurs.
• Chaque accès a aussi sa propre limite dans l'API : une réserve de 60 appels, puis 2 appels par seconde. Au-dessus, le code d'erreur est rate_limited.
• Un jeton d'accès est un secret. Gardez-le en mémoire ou dans un coffre à secrets. Ne l'écrivez pas dans une URL, un journal ou une ligne de commande.
• Un jeton n'atteint qu'une liste fermée de routes de l'API. Toute autre route répond 403, même avec un jeton valide.
• Aucun outil ne rend le contenu d'un fichier, un lien de téléchargement, les lignes de journal d'une tâche, la taille d'une sélection, le contenu d'un tenant Microsoft 365, une suppression, la gestion des utilisateurs ou une route de la plateforme.
• Un accès s'arrête aussi quand le compte n'est plus actif, quand l'appartenance au MSP est retirée, quand la vérification en deux étapes du compte est réinitialisée, ou quand le MSP est supprimé.
• Quand l'adresse du serveur MCP change, les jetons déjà donnés ne valent plus. Chaque utilisateur refait son consentement une fois.
• Une sauvegarde ou une restauration lancée par MCP sur un agent trop ancien est refusée avec le code agent_too_old. Voir Agent trop ancien.
• Les réglages de l'accès MCP ne se changent que dans le portail, avec une session et le rôle Administrateur. Ni une clé API ni un jeton MCP ne les change.

Journalisation

Chaque appel de l'API avec un jeton d'accès écrit une entrée dans le journal d'audit du MSP, avant le travail. L'entrée s'appelle Appel de l'API via MCP. L'auteur est l'utilisateur du jeton. L'objet est l'application.

Le journal porte aussi les entrées Accès MCP accordé, Accès MCP révoqué, Accès MCP activé et Accès MCP désactivé.

1. Ouvrez le portail.
2. Dans la barre du haut, cliquez sur Administration.
3. Cliquez sur Journal d'audit.
4. Lisez les entrées Appel de l'API via MCP.

Les entrées du travail lui-même suivent l'appel, par exemple la demande d'une restauration. Voir Journal d'audit.

La page Accès MCP donne aussi la date du dernier usage de chaque accès. Cette date est écrite au plus une fois par minute.

Le serveur MCP n'écrit jamais un jeton ni un argument d'outil dans ses journaux techniques.

Référence

• Outils MCP : Outils MCP.
• Outils de lecture : read.
• Outils d'action : operate.
• Outils d'enrôlement : enroll.
• Routes de l'API REST : API.