API REST et MCP

Utilisez REST et MCP lorsqu’un processus Opfield doit être reproductible, attribuable et indépendant du navigateur d’un opérateur. Un processus est terminé lorsque la ressource atteint l’état prévu, et non lorsque la requête HTTP est acceptée ou que l’appel d’outil revient.

L’API REST expose des opérations documentées sur les ressources, avec une authentification par session, jeton d’API ou OAuth selon le cas. Le MCP distant fournit des outils orientés tâches s’appuyant sur les mêmes scopes, validations, droits et piste d’audit.

L’automatisation doit :

utiliser une identité dédiée à privilèges minimaux ;
traiter 202 ou la création d’une tâche comme un travail accepté, puis interroger l’état durable ;
ne réessayer que les opérations idempotentes, envoyer un Idempotency-Key avec les créations qui l’acceptent, ou utiliser le contrat de nouvelle tentative de l’opération ;
traiter distinctement les échecs 401, 403, 409, 422 et de nœud hors ligne ;
éviter d’analyser le texte de l’interface lorsqu’un champ structuré de l’API existe ;
consigner les identifiants de ressources et de requêtes sans journaliser de secrets.

Utilisez le document OpenAPI servi par l’instance Opfield en cours d’exécution pour les schémas exacts des requêtes et des réponses. La version du schéma doit correspondre à l’instance automatisée ; ne copiez pas de corps de requête depuis une autre version. Les guides produit décrivent l’ordre des ressources requis et les conséquences opérationnelles que les schémas seuls ne peuvent pas exprimer.

Authentification et découverte

Choisissez une session, un jeton d’API ou un client OAuth selon l’appelant. Les clients du MCP distant s’autorisent via OAuth et découvrent des outils orientés tâches filtrés par les mêmes scopes et le même état du produit. La présence d’un outil ne prouve pas qu’une modification particulière d’une ressource sera admise.

Commencez l’automatisation en lisant la ressource cible et l’état de ses capacités. Résolvez des identifiants stables plutôt que d’extraire des noms de l’interface. Gardez séparés l’URL de base, le jeton et l’environnement afin qu’un script de développement ne puisse pas cibler la production par accident.

Savoir à quoi l’appelant a accès

Un accès limité à des dossiers, des nœuds ou des ressources individuelles est normal pour l’automatisation et les agents. Lisez le résumé d’accès de l’appelant avant de créer des ressources, et chaque fois qu’une liste revient vide ou qu’une création à la racine est refusée :

REST : GET /api/auth/me/access, avec une session, un jeton d’API ou un jeton OAuth.
MCP et AI Workspace : l’outil get_my_access, éventuellement avec une area comme docker_containers ou routes.
Ressource MCP : opfield://access.

Le résumé regroupe les accès par zone de produit. Pour chaque zone, il indique si l’accès est broad ou limited, liste les dossiers accordés (identifiant, nom et chemin), les nœuds, les comptes et les ressources avec les actions autorisées sur chacun, et indique où l’appelant peut créer : create.atRoot, create.folders et create.nodes, avec une indication howTo. L’objet principal nomme le type d’identifiant (session, api-token, oauth-token, mcp ou assistant). Seules une session de navigateur et AI Workspace reçoivent aussi l’identifiant, le nom, l’adresse e-mail et le groupe de permissions de l’utilisateur ; les jetons d’API, les jetons OAuth et les clients MCP ne reçoivent que principal: { credential, boundedByOwner: true }, car leur accès ne dépasse jamais l’accès actuel du propriétaire. Lorsqu’une connexion MCP est limitée, Opfield ajoute aussi une version courte du résumé aux instructions du serveur MCP au moment de la connexion.

La zone apps ne liste que les scopes d’app. Une app que l’appelant ne voit qu’à travers ses ressources n’y figure pas ; list_apps et get_app la renvoient avec access: "members". Voir Qui voit une app.

Travaillez à l’intérieur des droits listés :

Les points de terminaison et outils de liste ne renvoient que ce à quoi l’appelant a accès ; une liste vide n’est pas un refus.
list_resource_folders affiche chaque dossier sur lequel l’appelant détient un droit quelconque, y compris les dossiers vides, avec access.actions et access.canCreate.
Une création sans folderId cible la racine. Passez folderId, et nodeId lorsque l’opération en prend un, lorsque l’accès en création est limité.
Un refus opposé à un appelant limité — une création à la racine ou la lecture d’une ressource hors de ses droits — nomme les dossiers, nœuds et ressources que l’appelant peut utiliser et indique de passer folderId, aussi bien dans les réponses REST que dans les erreurs d’outils MCP et AI Workspace. Ne considérez une permission comme manquante que lorsque le résumé n’indique aucun droit pour l’action, où que ce soit.

Connecter Codex ou Claude Code via MCP

Opfield expose son serveur MCP distant authentifié à l’adresse :

https://opfield.example.com/api/mcp

Remplacez opfield.example.com par le nom d’hôte public canonique de votre installation Opfield. Utilisez la même origine HTTPS que celle qu’utilisent les opérateurs pour ouvrir Opfield. N’ajoutez pas un autre /mcp et ne faites pas pointer le client vers la racine de l’API REST.

Une fois connecté, le client peut découvrir les outils d’Opfield et n’effectuer que les opérations autorisées à l’utilisateur connecté. MCP n’accorde pas d’accès administrateur et ne contourne ni les scopes de ressources, ni les droits du plan, ni les confirmations, ni la journalisation d’audit.

Préparer Opfield

Un administrateur effectue ces étapes une seule fois :

Ouvrez Settings, sélectionnez Features et trouvez OAuth and MCP access.
Activez Enable MCP server.
Laissez Extended MCP compatibility activé pour les clients normaux. Ne le désactivez que lorsqu’un client charge tout le catalogue d’outils dans son contexte et ne peut pas gérer sa taille.
Laissez OAuth extended callback compatibility désactivé pour Codex et Claude Code. Leurs rappels sur la boucle locale fonctionnent avec la politique par défaut, plus sûre.
Accordez à l’utilisateur qui se connecte Use MCP (mcp:use) ainsi que les scopes ordinaires correspondant aux ressources que ce client peut lire ou modifier.

L’utilisateur doit aussi pouvoir se connecter à Opfield dans un navigateur. Si la connexion fonctionne mais qu’un outil ou une ressource manque, examinez l’appartenance aux groupes et les scopes de ressources au lieu d’élargir la politique de rappel OAuth.

Connecter Codex

Ajoutez Opfield, effectuez la connexion OAuth et vérifiez la connexion :

codex mcp add opfield --url https://opfield.example.com/api/mcp
codex mcp login opfield
codex mcp list

La commande de connexion ouvre Opfield dans votre navigateur. Connectez-vous avec l’utilisateur Opfield prévu, examinez l’accès demandé et approuvez-le. Codex stocke l’identifiant OAuth obtenu ; vous ne créez ni ne collez de jeton d’API.

Dans l’application de bureau Codex ou l’extension pour IDE, vous pouvez plutôt ajouter un serveur MCP Streamable HTTP avec la même URL et sélectionner Authenticate. L’application de bureau, la CLI et l’extension pour IDE partagent la configuration MCP de Codex.

Connecter Claude Code

Ajoutez Opfield comme serveur HTTP distant pour votre compte utilisateur :

claude mcp add --transport http opfield --scope user https://opfield.example.com/api/mcp
claude mcp login opfield
claude mcp get opfield

Vous pouvez aussi ouvrir une session Claude Code interactive, saisir /mcp, sélectionner opfield et effectuer l’authentification dans le navigateur. N’utilisez --scope project à la place de --scope user que lorsque le dépôt doit partager la définition du serveur via .mcp.json ; chaque développeur se connecte malgré tout avec son propre compte Opfield.

Fonctionnement du flux OAuth

Vous n’avez pas besoin d’enregistrer manuellement un client OAuth pour Codex ou Claude Code :

le client contacte /api/mcp et reçoit les informations de découverte OAuth d’Opfield ;
le client s’enregistre lui-même et démarre le flux Authorization Code avec PKCE ;
Opfield ouvre un écran de connexion et de consentement dans le navigateur ;
l’utilisateur approuve un accès borné par ses scopes Opfield actuels et peut le limiter à des dossiers, des environnements d’app ou des ressources, par exemple depuis l’en-tête d’une section de scopes qui affiche Everywhere sous Review N scopes ; voir Restreindre les jetons et les autorisations OAuth ;
Opfield émet un jeton d’accès OAuth pour la ressource MCP ;
le client stocke cet identifiant et l’envoie à /api/mcp lors des requêtes suivantes.

Opfield n’accepte que les jetons d’accès OAuth émis pour sa ressource MCP. Les cookies du navigateur, les jetons d’API gw_ ordinaires, les jetons de journalisation gwl_ et les jetons Opfield Inference gwi_ sont refusés. Le serveur revérifie les scopes actuels de l’utilisateur et mcp:use ; retirer l’accès arrête donc les opérations MCP futures, même si le client a découvert les outils auparavant.

Vérifier la connexion

Commencez par une requête en lecture seule :

Liste les nœuds Opfield auxquels j'ai accès et résume leur état actuel. Ne modifie rien.

Confirmez que le client signale opfield comme connecté, que seules les ressources attendues sont visibles, qu’une lecture réussit, qu’une action hors des scopes de l’utilisateur est refusée, et qu’Opfield attribue l’appel à l’utilisateur attendu dans le journal d’audit.

Dépannage de la connexion MCP

Le point de terminaison renvoie 404 : activez Settings → Features → OAuth and MCP access → Enable MCP server et vérifiez que l’URL se termine par /api/mcp.
Le client exige une authentification : exécutez codex mcp login opfield ou claude mcp login opfield. Dans un client interactif, utilisez /mcp.
La connexion réussit mais Opfield renvoie 403 : le compte a besoin de mcp:use et d’au moins un scope de ressource effectif. Un droit limité à un dossier ne voit que les ressources de ce dossier ; une création ailleurs est refusée. Demandez à l’agent d’appeler get_my_access et de créer dans l’un des dossiers qu’il liste ; voir Savoir à quoi l’appelant a accès.
Un client envoie un nom de scope qui n’existe plus : Opfield accepte encore les noms de scopes retirés et accorde leurs remplaçants.
Le client épuise son contexte avec trop d’outils : désactivez Extended MCP compatibility pour utiliser le catalogue initial compact et la découverte par catégories.
Opfield refuse le rappel OAuth : mettez d’abord le client à jour et réessayez. Les rappels normaux de Codex et Claude Code sur la boucle locale ne nécessitent pas OAuth extended callback compatibility.
Une connexion enregistrée a cessé de fonctionner : vérifiez si l’autorisation OAuth, mcp:use, les scopes de ressources ou l’URL canonique d’Opfield ont changé. Authentifiez-vous à nouveau au lieu de substituer un jeton d’API ordinaire.

Opérations durables

De nombreuses modifications de l’infrastructure renvoient une tâche ou une opération acceptée plutôt qu’un résultat terminé :

soumettez la requête validée ;
stockez les identifiants de ressource, de tâche, d’opération et de requête renvoyés ;
interrogez l’état durable de l’opération ou abonnez-vous à celui-ci ;
examinez les détails structurés des échecs ;
vérifiez de façon indépendante l’état de la ressource obtenu ;
ne réessayez que selon le contrat d’idempotence de l’opération.

Ne transformez pas directement un délai de transport dépassé en une seconde requête de création ou de suppression. La première requête peut avoir atteint le démon propriétaire et attendre sa réconciliation. Une création envoyée à un point de terminaison qui accepte un Idempotency-Key fait exception : réessayez-la avec la même clé.

Nouvelles tentatives sûres avec Idempotency-Key

Certains points de terminaison de création acceptent un en-tête facultatif Idempotency-Key de 1 à 255 caractères ASCII imprimables, par exemple un UUID. Le document OpenAPI liste l’en-tête exactement sur ces opérations :

Docker : création et duplication de conteneurs, et création de Deployments, de projets Compose, de ressources à partir d’une source Git, de volumes, de réseaux et de registres ;
Ingress et certificats : Routes (POST /api/proxy-hosts), dossiers de Routes, domaines, certificats ACME et autorités de certification racines et intermédiaires ;
Bases de données et stockage : connexions de bases de données, bases de données managées, connexions de stockage et stockage managé ;
Autres : projets Pages, règles d’alerte et destinations SIEM.

Générez une nouvelle clé pour chaque opération logique, et n’envoyez à nouveau la même clé que lorsque vous réessayez cette requête après un délai dépassé ou une connexion interrompue :

curl -X POST https://opfield.example.com/api/domains \
  -H "Authorization: Bearer $OPFIELD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6c1e-8a55-4c43-9d4e-2f1f8c3d9b10" \
  -d '{"domain":"app.example.com"}'

Une clé appartient au jeton d’API, au jeton OAuth ou à la session de navigateur qui l’a envoyée, avec les scopes effectifs actuels de cet appelant, la méthode et le chemin exact. Après un changement de scopes, la même clé repart de zéro ; un rejeu ne survit donc jamais à un accès révoqué.
Une nouvelle tentative avec la même clé et la même requête — même chaîne de requête et même corps JSON, quel que soit l’ordre des clés — renvoie la réponse stockée avec l’en-tête Idempotency-Replayed: true et ne crée rien de nouveau. Opfield conserve le résultat pendant 24 heures, chiffré avec sa clé maîtresse, et consigne chaque rejeu dans le journal d’audit sous api.idempotency.replay.
La même clé avec une requête différente renvoie 422 IDEMPOTENCY_KEY_REUSED. La même clé pendant que la première requête est encore en cours renvoie 409 IDEMPOTENCY_KEY_IN_PROGRESS avec Retry-After. Une clé invalide renvoie 400 IDEMPOTENCY_KEY_INVALID.
Opfield ne stocke jamais une réponse qui semble contenir du matériel secret, comme un jeton, un mot de passe, une clé privée ou des identifiants, ni une réponse de plus de 1 Mio. Il enregistre seulement que la requête s’est terminée, et une nouvelle tentative renvoie 409 IDEMPOTENCY_RESPONSE_WITHHELD avec le code d’origine et Location lorsqu’il est connu : recherchez la ressource au lieu de réessayer.
Seules les réponses 2xx et les réponses 400, 404, 409 et 422 avec un corps JSON ou vide sont enregistrées. Les réponses 401, 403, 5xx, en flux et de téléchargement ne le sont pas ; une nouvelle tentative après celles-ci exécute donc à nouveau la requête.
Non couvert : chaque point de terminaison hors de la liste ci-dessus, qui s’exécute normalement et ignore l’en-tête. Cela inclut délibérément les points de terminaison qui renvoient un secret une seule fois ou reprennent des entrées sensibles : jetons d’API, d’inférence, d’ingestion de journalisation et de déploiement Pages, enrôlement des nœuds, clés d’accès et identifiants, liaisons, Access Lists et webhooks de notification. Les corps de requête de plus de 1 Mio et les téléversements non JSON s’exécutent aussi sans idempotence, de même que tout le reste tant que Redis, qui stocke les clés, est indisponible.

Les outils MCP de création acceptent un argument facultatif idempotencyKey avec les mêmes règles. La clé est liée au jeton MCP et à ses scopes, aux scopes actuels du propriétaire et à l’outil. Seuls les résultats réussis sont stockés ; une erreur d’outil peut donc être retentée avec la même clé ; un résultat rejoué porte _meta.idempotencyReplayed: true et est audité. Un résultat qui semble contenir un secret n’est pas stocké, et une nouvelle tentative renvoie IDEMPOTENCY_RESULT_WITHHELD. L’argument est proposé sur :

Docker : create_docker_container, duplicate_docker_container, et l’opération de création de manage_docker_deployment, manage_docker_compose, manage_docker_source, manage_docker_volume, manage_docker_network, manage_container_link et manage_docker_registry ;
Ingress : create_route, create_route_folder et create_domain ;
Certificats : request_acme_cert, l’opération de téléversement de manage_ssl_certificate, create_root_ca et create_intermediate_ca ;
Bases de données et stockage : l’opération de création de manage_database_connection, manage_managed_database, manage_storage_connection et manage_managed_storage ;
Autres : l’opération project_create de manage_pages, create_alert_rule et create_siem_destination.

Les outils qui renvoient un secret ou reprennent des entrées sensibles — create_node, create_access_list, create_webhook, la création de liaisons, la création de jetons et de clés d’accès, et issue_certificate — n’acceptent pas cet argument. Les opérations de cycle de vie Compose de manage_docker_compose conservent leur propre argument idempotencyKey avec sa signification antérieure.

Transférer les charges utiles volumineuses via des liens à usage unique

Les appels d’outils sont un mauvais canal pour les fichiers. Pour les charges utiles volumineuses, les outils MCP renvoient un lien à usage unique accompagné d’une commande curl prête à l’emploi qu’exécute un shell du côté de l’agent ; les octets transitent par Opfield, jamais par le modèle :

Pages : l’opération link de upload_pages_artifact accepte une archive, un dossier de build empaqueté ou un unique fichier HTML. Le téléversement peut atteindre la File upload limit (100 Mo par défaut, 500 Mo au maximum) ; voir Vue d’ensemble de Pages. Sans shell, les opérations begin, chunk et finalize acceptent au plus 1 Mio par fragment.
Archives de conteneurs : les opérations link de download_docker_archive et upload_docker_container_archive exportent et importent des archives .gwca.
Objets de stockage : download_storage_object renvoie un lien, valable 15 minutes, qui télécharge un objet de n’importe quelle taille, et upload_storage_object téléverse par fragments qu’Opfield vérifie.

Un lien ne fonctionne qu’une fois, appartient au jeton qui l’a demandé et est revérifié par rapport aux permissions actuelles du propriétaire au moment de son utilisation. Traitez-le comme un identifiant de courte durée.

Gestion des erreurs

400 ou 422 : corrigez la forme de la requête ou les entrées de validation ;
401 : actualisez ou remplacez l’authentification ;
403 : distinguez un scope manquant d’un droit de plan manquant ;
404 : vérifiez la visibilité de la ressource autant que son existence ;
409 : examinez le conflit de cycle de vie, le quota ou l’état actuel ;
429 : appliquez un délai d’attente borné et respectez les indications du serveur ;
5xx ou nœud hors ligne : conservez les identifiants de requêtes et vérifiez l’état durable de la tâche avant de réessayer.

Les erreurs d’outils MCP et AI Workspace commencent par le même code que la réponse REST, par exemple NOT_FOUND, STORAGE_NOT_FOUND ou NGINX_CONFIG_FAILED, suivi du message et des détails ; une erreur de schéma se lit VALIDATION_ERROR avec les champs en échec. Une requête vers un chemin /api inconnu renvoie un 404 NOT_FOUND JSON au lieu de la page de la Console.

Règles d’utilisation de MCP

Les outils MCP couvrent chaque opération sur les ressources et de gestion autorisée par les scopes de l’autorisation OAuth, y compris la configuration et les fichiers des nœuds, les migrations Docker, le backend de journalisation, les paramètres d’Opfield, les utilisateurs et les groupes, les opérations sur le Relay Pool et les mises à jour, l’administration de l’inférence, l’hébergement, ainsi que les connecteurs GitLab, GitHub, Git générique, Cloudflare et SSH externe. MCP n’expose pas les éléments internes d’AI Workspace, comme les conversations, les plans et les bacs à sable, ni les outils qui créent des jetons d’API ou des autorisations OAuth. Voir Ce que les jetons peuvent et ne peuvent pas faire.

La création de Routes et de domaines ne nécessite pas de permissions sur les nœuds : create_route et create_domain peuvent omettre le nœud lorsqu’un domaine enregistré ou le seul nœud Ingress éligible le détermine (pour les Routes, ce nœud doit être en ligne), et list_route_ingress_nodes liste les nœuds sur lesquels l’appelant peut créer des Routes. Voir Choisir le nœud Ingress.

Le serveur MCP indique la version d’Opfield comme sa propre version. manage_opfield_diagnostics examine Opfield lui-même ; voir Diagnostics d’Opfield. Lorsqu’un outil MCP définit l’environnement d’un Deployment, il le fusionne avec l’environnement enregistré, contrairement à la route REST de déploiement ; voir Publier une nouvelle version.

Utilisez MCP pour des opérations orientées objectif dans lesquelles le schéma de l’outil apporte de la sécurité et du contexte sur les ressources. Lisez les descriptions des outils et les avertissements renvoyés, passez des identifiants de ressources exacts et traitez le contenu externe comme une entrée non fiable. Les appels MCP sont audités et ne doivent pas servir à contourner les contrôles de confirmation, de permissions, de droits ou de cycle de vie.

Vérification

Pour chaque chemin d’automatisation, testez une action autorisée, une action refusée, un échec de validation, un succès asynchrone et une opération interrompue. Confirmez l’attribution dans l’audit et assurez-vous que les journaux masquent les identifiants et les champs de requête sensibles.

Concevoir des clients fiables

Modélisez l’automatisation comme une réconciliation plutôt que comme une suite de clics à l’aveugle. Lisez la ressource actuelle, comparez-la avec l’état souhaité, soumettez la plus petite modification nécessaire et vérifiez l’état obtenu signalé par le propriétaire. Utilisez des identifiants stables dans l’état stocké et réservez les noms lisibles à l’affichage. Lorsqu’une API expose un identifiant d’opération ou de tâche, enregistrez-le avec l’exécution de l’automatisation afin qu’un opérateur puisse corréler un délai dépassé avec l’historique d’Opfield.

Définissez séparément des délais bornés pour la connexion, la requête et l’opération dans son ensemble. Un délai HTTP court peut coexister avec une tâche durable de longue durée. Réessayez les lectures et les mises à jour explicitement idempotentes avec un délai exponentiel plafonné et une gigue. Ne réessayez pas automatiquement les créations, suppressions, migrations, restaurations ou rotations d’identifiants après un délai dépassé ambigu, sauf si la requête portait un Idempotency-Key vers un point de terminaison qui l’accepte, ou si l’opération existante a été réconciliée.

Versionnez le client par rapport au document OpenAPI et aux versions d’Opfield avec lesquelles il a réellement été testé. Refusez les champs et états destructifs inconnus plutôt que de les ignorer silencieusement. Si une version modifie un contrat de cycle de vie, mettez à jour le client et ses tests de recette avant de le déployer sur toutes les installations.

Déploiement et retour arrière sûrs

Exécutez une nouvelle automatisation sur un dossier ou un ensemble de ressources jetables avec des scopes proches de la production. Capturez la requête prévue, la tâche obtenue, l’enregistrement d’audit et une vérification indépendante de l’état. Déployez d’abord sur une installation ou un domaine de panne, puis observez les erreurs et le délai de réconciliation avant d’étendre.

Un retour arrière consiste normalement à désactiver l’appelant, à arrêter les nouvelles soumissions et à appliquer un retour arrière produit pris en charge aux ressources déjà modifiées. Il ne consiste pas à supprimer des tâches ou à modifier l’état souhaité dans PostgreSQL. Conservez les identifiants de requêtes et les métadonnées des charges utiles en échec, secrets retirés, afin que le responsable produit puisse distinguer un défaut du client d’une panne d’Opfield ou d’un démon.