Routes du catalogue métier

Le catalogue business est la liste des serveurs MCP que la plateforme sait décrire et proposer. Toutes les routes vivent sous /api/v1/mcp/catalog-business (il n'existe aucun préfixe mcp/gateways : d'anciennes versions de ce livre le citaient à tort). Elles sont déclarées dans crates/forge-api/src/router.rs et implémentées dans crates/forge-api/src/routes/mcp_catalog_business.rs.

Authentification. Toutes ces routes exigent un jeton (Authorization: Bearer <token> ou cookie jwt). Les opérations de cycle de vie sont de plus réservées aux rôles admin et owner : un autre rôle reçoit 403 FORBIDDEN.

<hote-api> est défini dans Swagger.

État réel. La lecture du catalogue est opérationnelle. Les opérations qui piloteraient des conteneurs (deploy, start, stop, restart, secrets, security, déploiement de profil) répondent aujourd'hui 503 avec le code FEATURE_PENDING : l'adaptateur Podman n'est pas branché sur forge-api. C'est une capacité prévue (spec 16, tâche P5.5 ; voir la section « Cycle de vie : prévu, répond 503 » plus bas), pas une capacité livrée.

Lecture du catalogue

GET /api/v1/mcp/catalog-business

Paramètre de requête : category (valeur exacte d'une catégorie, par exemple Communication ou CRM%20%26%20ERP une fois encodé ; all ou vide = pas de filtre). Le paramètre tier est accepté mais n'est pas appliqué : le catalogue renvoie tous les serveurs et le client filtre.

curl "https://<hote-api>/api/v1/mcp/catalog-business?category=Communication" \
  -H "Authorization: Bearer <token>"

Réponse : {"servers": [...], "total": N}. Il n'y a pas de pagination. Une fiche porte ces champs, lus dans routes/data/catalog-business.json :

{
  "id": "odoo",
  "name": "Odoo",
  "description": "ERP/CRM open source complet: ventes, achats, stock, comptabilite, RH et plus.",
  "category": "CRM & ERP",
  "iconName": "Briefcase",
  "provider": "Odoo SA",
  "country": "Belgique",
  "endpoints": 331,
  "status": "available",
  "certifications": ["RGPD", "ISO27001", "SOC2", "Gaia-X"],
  "license": "LGPL-3.0",
  "documentation": "https://www.odoo.com/documentation",
  "verified": true,
  "pullCount": 1247,
  "tags": ["erp", "crm", "comptabilite", "rh", "stock", "ventes"],
  "version": "17.0",
  "tier": "official"
}

Le catalogue embarqué contient 108 fiches (test catalog_embeds_full_business_catalogue). GET .../{id} renvoie la fiche seule, ou 404 NOT_FOUND si l'identifiant est inconnu.

Les champs certifications, verified et pullCount sont des valeurs écrites dans le fichier embarqué. Aucun code de la plateforme ne les calcule ni ne les vérifie : ne les lisez ni comme une certification obtenue, ni comme un compteur de téléchargements mesuré.

GET /api/v1/mcp/catalog-business/{id}/status

Rend l'état honnête d'un serveur : sa disponibilité au registre, pas celle d'un conteneur.

{
  "serverId": "odoo",
  "containerId": null,
  "port": null,
  "uptime": null,
  "startedAt": null,
  "status": "available",
  "proven_operational": true,
  "runtime": { "known": false, "reason": "podman_adapter_not_wired" }
}

status vaut available si le connecteur est dans le registre, sinon not_registered. Un identifiant absent du catalogue rend 404.

GET /api/v1/mcp/catalog-business/profiles

Les profils sont lus dans le fichier de profils du dépôt. La réponse est {"profiles": [...]}. Il y en a quatre :

Ces 37 serveurs sont ceux du fichier de profils, pas les 108 fiches du catalogue embarqué : ce sont deux inventaires différents.

GET /api/v1/mcp/catalog-business/deployed

Rend la liste des identifiants de serveurs prouvés opérationnels par un audit en direct (OPERATIONAL_PROVEN_LIVE, dans forge-core), sous la forme d'un tableau JSON d'identifiants. Ce n'est pas un inventaire de conteneurs Podman.

Exécuter un outil

POST /api/v1/mcp/catalog-business/tools/call prend server, tool et args (forme de la réponse : voir API-as-a-Service EU souverain) :

curl -X POST "https://<hote-api>/api/v1/mcp/catalog-business/tools/call" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"server":"searxng","tool":"query","args":{"q":"reglement ia"}}'

GET .../{id}/registry-tools liste les outils d'un connecteur et répond {"id": ..., "registry_tools": [...]} ; pour un identifiant absent du registre, la réponse reste 200 avec "registry_tools": [] et un champ error. GET .../tools répond {"tools": [...], "total": N} : les outils des connecteurs autorisés. La route voisine GET .../{id}/tools répond toujours {"id": ..., "tools": []} : elle est un emplacement de compatibilité, utilisez registry-tools.

Note sur GET /api/v1/stats/catalog-business. Cette route compte les lignes de la table des modèles personnalisés et renvoie {"total": N, "last_24h": M}. Elle ne décrit pas le catalogue de serveurs.

Cycle de vie : prévu, répond 503

Un appelant sans rôle admin ou owner reçoit d'abord 403 (et la tentative est auditée) ; un administrateur reçoit le 503. La réponse porte l'en-tête Retry-After: 86400 et ce corps :

{
  "error": {
    "code": "FEATURE_PENDING",
    "message": "MCP catalog-business lifecycle deferred to spec 16 REQ-5 (POST <route de deploiement prevue>) + Podman socket mount for forge-api"
  },
  "feature_pending": "catalog_business",
  "tracking": "V1: routes/mcp-streamable-http/index.ts L370-377"
}

Conséquences pour votre intégration : ne programmez pas de déploiement par cette API aujourd'hui. Le rapport de scan Trivy et le SBOM par serveur ne sont pas servis par .../{id}/security (503). Le SBOM CycloneDX de la plateforme elle-même est public sur GET /.well-known/sbom. Les secrets d'un locataire se gèrent par /api/v1/credentials (voir le chapitre « Routes des ressources »).

Voir aussi

• Routes MCP : le transport par session qui exécute les mêmes outils
• Routes des ressources : identifiants, document stores et autres ressources du locataire par l'API
• Parcourir le catalogue de services et préparer un déploiement : parcours pas à pas de ces routes, avec leurs réponses réelles
• MCP et Orchestrateur : les pages de l'application qui présentent ce catalogue
• Connecteurs MCP : connecteurs décrits dans ce livre et statuts du catalogue