Guide pratique des interfaces REST et MCP de GenOS, établi à partir des contrats source. Le serveur GenOS applique l’authentification, le scope tenant et les permissions d’outil.
client → authentification → scope tenant → permissions et politiques → transport MCP → résultat structuréEnvoyez un jeton d’accès GenOS dans Authorization: Bearer. L’exécution MCP exige mcp:execute_safe et un scope explicite comprenant une organisation et un projet. Envoyez les deux en-têtes tenant; les identifiants doivent correspondre et le principal authentifié doit y être autorisé.
Authorization: Bearer <access-token>
X-Organization-Id: <organization-id>
X-Project-Id: <project-id>GenOS vérifie les origines navigateur à partir de sa liste par défaut et de GENOS_ALLOWED_ORIGINS. Ajoutez l’origine exacte du site public à ce paramètre avant une connexion depuis un navigateur. Ne faites pas transiter un jeton partagé par le serveur web public.
GENOS_ALLOWED_ORIGINS=https://genos.workL’enveloppe HTTP accepte toolName ou tool_name et timeoutMs ou timeout_ms. Les arguments de l’outil doivent respecter son schéma JSON; leurs noms canoniques sont en snake_case. L’exemple lance une orchestration locale supervisée et attend son résultat.
curl --request POST "$GENOS_URL/api/mcp/execute" \
--header "Authorization: Bearer $GENOS_TOKEN" \
--header "X-Organization-Id: $GENOS_ORG" \
--header "X-Project-Id: $GENOS_PROJECT" \
--header "Content-Type: application/json" \
--data '{"toolName":"genos_orchestrate","args":{"mission":"Summarize the approved task","executor":"local","background":false},"timeoutMs":60000}'Ces routes de lecture et d’exécution contrôlée servent à lister les outils, obtenir leurs schémas d’arguments ou les essayer via le transport MCP configuré. Un appel de test réussi peut exécuter le véritable outil aval.
GET /api/toolsreadListe les outils visibles.
GET /api/tools/:name/schemareadRetourne le schéma d’entrée courant.
POST /api/tools/testmcp:execute_safe + scope tenantTeste via le transport MCP configuré.
POST /api/tools/dry-runmcp:execute_safeSimule l’outil dans l’état VFS fourni; ce n’est pas un appel d’exécution.
POST /api/mcp/executemcp:execute_safe + scope tenantExécute l’outil si le registre et les politiques l’autorisent.
Ce schéma dépend de la version; récupérez le schéma courant avant d’utiliser des champs facultatifs. Le petit exemple fixe l’exécuteur local et l’exécution au premier plan.
{
"mission": "string (required)",
"worker_assignments": "optional",
"strategy": "optional",
"background": false,
"executor": "local",
"provider": "optional",
"modelId": "optional"
}Les arguments MCP utilisent snake_case. L’enveloppe REST accepte temporairement camelCase pour ses deux champs seulement. N’envoyez pas deux alias avec des valeurs contradictoires. La version MCP est genos.mcp/v1.
{
"toolName": "genos_replay",
"args": { "snapshot_id": "snap-example" },
"timeoutMs": 30000
}Vérifiez le statut HTTP et le corps propre à l’outil. REST n’emploie pas une enveloppe de succès unique. Une erreur peut contenir error.code, error.message, requestId, traceId et details.
400Requête ou arguments invalides401Jeton absent ou invalide403Permission, scope ou politique refusé404Route ou outil introuvable429Limitation de débit502Transport MCP aval en échec503Service, outil ou garde-fou indisponible504Délai dépassé{
"error": {
"code": "ZERO_TRUST_DENIED",
"message": "Tool execution denied.",
"requestId": "req-example",
"traceId": "trace-example"
}
}Le service HTTP expose des sondes de santé légères. gRPC et la CLI Rust ont leurs propres contrats, distincts de REST et MCP; consultez la documentation source et les fichiers proto.
GET /healthz
GET /readyz
GET /livez
gRPC: 127.0.0.1:50051
MCP protocol: genos.mcp/v1Ces routes appartiennent au site GenOSWork, pas au runtime GenOS. Elles publient des connaissances en lecture seule, sans identifiant. OpenAPI décrit leurs réponses; llms.txt donne une carte des contenus.
Chaque contrat est épinglé à la même révision V3. Vérifiez le schéma du runtime déployé avant un appel effectif.