Brancher un agent par MCP

Le serveur MCP de Bastide donne à votre agent de code les mêmes gestes que la console : créer un projet, déployer, lire les journaux, revenir en arrière. Cette page explique comment brancher Claude Code, Claude Desktop, Cursor ou tout autre client MCP, comment l'agent découvre ses outils, et ce que coûtent leurs réponses en jetons.

Ce qu'il faut savoir d'abord

• L'adresse du serveur est unique pour toutes les organisations : https://mcp.bastide.app/mcp. C'est le jeton présenté qui dit qui vous êtes et ce que vous pouvez faire.
• Le serveur n'exécute aucun modèle de langage et n'appelle aucun serveur MCP tiers. Le raisonnement a lieu chez votre agent, avec votre abonnement.
• Chaque outil appelle l'API de Bastide sous votre identité : votre rang sur l'organisation ou le projet, borné par les portées du jeton. Un agent ne peut jamais faire plus que vous. Le détail est dans Ce qu'un agent peut faire.
• Un outil MCP porte le nom de son opération, les points remplacés par des soulignés : deployment.create devient deployment_create.

Deux façons de s'authentifier

Note. L'enregistrement dynamique des clients OAuth (RFC 7591) n'est pas ouvert sur bastide.app. Un client qui ne connaît que ce mode, comme Cursor aujourd'hui, se branche avec un jeton personnel en en-tête.

L'autorisation OAuth

1. Le client appelle le serveur sans jeton. Le serveur répond 401 avec l'en-tête WWW-Authenticate, qui désigne ses métadonnées : https://mcp.bastide.app/.well-known/oauth-protected-resource/mcp. Le serveur d'autorisation est https://api.bastide.app.
2. Le client ouvre votre navigateur sur l'écran Autoriser un client MCP de la console (https://console.bastide.app/autoriser). Connectez-vous si besoin.
3. L'écran montre le nom que le client se donne, son adresse, l'adresse de retour et les portées demandées. Le nom est écrit par le client : vérifiez l'adresse. Choisissez Autoriser ou Refuser. La demande expire au bout de dix minutes.
4. Le client reçoit un jeton d'agent valable trente minutes et un jeton de renouvellement valable trente jours, qui change à chaque usage. Le code d'échange est lié au défi PKCE (S256), vit soixante secondes et ne sert qu'une fois.

Un client qui ne demande aucune portée reçoit la seule portée project:read. Les portées accordées ne dépassent jamais votre rang.

Retirer un client autorisé

Ouvrez Compte, section « Clients MCP autorisés ». Chaque client y figure avec ses portées, la date de l'autorisation et celle de son dernier jeton. Retirer refuse ses jetons dès l'appel suivant. Les opérations sous-jacentes sont mcp_client.list et mcp_client.revoke ; elles ne sont pas des outils MCP, un agent ne gère pas ses propres autorisations.

Le jeton personnel

Ouvrez Compte, section « Vos jetons », puis Frapper un jeton. Donnez-lui un nom, une durée (de 7 à 365 jours) et les portées nécessaires. Pour le parcours de déploiement, project:read, project:write et deploy:write suffisent ; ajoutez secrets:write si l'agent doit écrire des variables. Le jeton n'est montré qu'une fois. Voir Comptes de service et jetons.

Claude Code

Avec l'autorisation OAuth, ajoutez le serveur, puis lancez /mcp dans une session pour ouvrir la connexion dans le navigateur :

claude mcp add --transport http bastide https://mcp.bastide.app/mcp

Avec un jeton personnel, passez l'en-tête :

claude mcp add --transport http bastide https://mcp.bastide.app/mcp \
  --header "Authorization: Bearer $BASTIDE_TOKEN"

Pour partager la configuration avec l'équipe sans y écrire le jeton, utilisez le fichier .mcp.json à la racine du dépôt. Claude Code y remplace ${BASTIDE_TOKEN} par la variable d'environnement de chacun :

{
  "mcpServers": {
    "bastide": {
      "type": "http",
      "url": "https://mcp.bastide.app/mcp",
      "headers": { "Authorization": "Bearer ${BASTIDE_TOKEN}" }
    }
  }
}

Claude Desktop

Ajoutez un connecteur personnalisé (« Add custom connector ») avec l'adresse https://mcp.bastide.app/mcp. Pour l'identité du client OAuth, choisissez l'identité publiée de Claude, qui repose sur un document de métadonnées : c'est le mode que Bastide accepte. Le connecteur vous envoie alors sur l'écran Autoriser un client MCP à la première connexion. L'emplacement exact du menu dépend de votre version et de votre offre Claude : reportez-vous à la documentation de Claude.

Cursor

Cursor lit .cursor/mcp.json dans le projet, ou ~/.cursor/mcp.json pour tous vos projets. Sa connexion OAuth passe par l'enregistrement dynamique, qui n'est pas ouvert : utilisez un jeton personnel, lu d'une variable d'environnement.

{
  "mcpServers": {
    "bastide": {
      "url": "https://mcp.bastide.app/mcp",
      "headers": { "Authorization": "Bearer ${env:BASTIDE_TOKEN}" }
    }
  }
}

Tout autre client MCP

• Transport HTTP « streamable » : des enveloppes JSON-RPC 2.0 postées sur https://mcp.bastide.app/mcp. Le serveur ne tient aucune session et n'ouvre aucun flux : un GET reçoit 405.
• Révisions acceptées à l'ouverture (initialize) : 2025-11-25, 2025-06-18 et 2025-03-26.
• Méthodes servies : initialize, ping, tools/list, tools/call, resources/list, resources/read.
• Le premier appel sans en-tête Authorization reçoit le défi 401 : c'est lui qui déclenche la découverte OAuth chez un client qui la connaît.

Attention. Sur ces révisions du protocole, une opération qui demande la confirmation d'une personne ne peut pas être confirmée depuis le client : l'outil rend une erreur qui vous renvoie à la console. C'est le cas de la suppression d'un projet ou d'un domaine.

Découvrir les outils

Le serveur sert trois profils d'outillage, choisis par le paramètre profile de l'adresse :

Le profil essentiel comprend project_list, project_read, project_create, project_settings_write, deployment_create, deployment_read, deployment_log_read, task_read, deployment_cancel, deployment_rollback, env_list, env_pull_nonproduction, env_write_nonproduction, backend_read, action_undo, et l'outil de découverte toolset_read. L'écriture des variables de production n'y est pas, à dessein. project_create_with_backend, qui crée le projet, sa base et son premier déploiement en un appel, est dans complet.

Deux outils sont servis par le serveur lui-même, sans appeler l'API :

• toolset_read rend, pour un domaine (l'objet du nom d'outil : deployment, env, database…), le schéma d'entrée de chaque outil, un exemple d'appel et les clés de sa sortie. Un agent lit ainsi trois schémas au lieu de charger tout le catalogue.
• documentation_search cherche dans la documentation de la plateforme (opérations, codes d'erreur, ressources) et rend des extraits bornés par un budget de jetons, chacun avec l'adresse de sa source. L'appariement est lexical : aucun modèle n'est appelé.

Chaque outil publie dans son _meta sa classe de réversibilité (bastide/reversibility), sa portée et son rang minimal, ses codes d'erreur, ses limites de débit et s'il exige une confirmation. Le catalogue complet, avec le schéma de chaque entrée, est publié dans mcp-tools.json et dans la référence MCP. La liste des outils se met en cache une heure : elle est la même pour tous.

Le budget de jetons des résultats

Votre agent paie ses jetons. Chaque outil annonce dans _meta le budget indicatif de son résultat (bastide/tokenBudget) : 700 pour task_read, 1 200 pour deployment_read, 8 000 pour deployment_log_read, par exemple. Les lectures longues sont découpées pour tenir dans ce budget :

• deployment_log_read s'arrête à limite lignes ou au budget, et nextRank dit où reprendre (argument depuis).
• Les listes sont paginées par curseur, cent éléments au plus par page.
• documentation_search accepte un argument tokenBudget, de 100 à 4 800 jetons (1 200 par défaut), que la réponse ne dépasse jamais.

Les ressources MCP

Une ressource se lit par resources/read, sans appel d'outil. Cinq sont servies :

Une ressource privée est servie par la même opération qu'un outil (project.read, database.posture.read), sous les mêmes droits. Les ressources d'incident et de conventions d'un projet ne sont pas encore disponibles.

Limites

Elles ne dépendent pas du palier.

• Par jeton, 600 appels par minute, dont 60 écritures, comme l'API.
• Par jeton présenté au serveur MCP, 2 000 appels par heure, dont 200 qui modifient quelque chose. Au-delà, le serveur répond 429 avec Retry-After. Un client qui insiste malgré ce délai (vingt refus dans l'heure) voit son jeton gelé, au plus vingt-quatre heures, et vous êtes prévenu.
• Cinq créations de projet par jour glissant et par organisation par la voie des agents.

Erreurs fréquentes

Chaque erreur porte un code stable, sa cause et l'appel suivant à faire, sous le nom de l'outil. Le catalogue complet est la ressource glowsoft://docs/errors.

Voir aussi

• Ce qu'un agent peut et ne peut pas faire
• Créer un projet et Déployer
• Comptes de service et jetons
• La référence MCP

Signaler une erreur sur cette page