API-as-a-Service EU souverain

Ce chapitre décrit ce que la plateforme fait aujourd'hui pour exposer des sources de données européennes sous forme d'appels JSON structurés, et ce qui reste prévu. À la fin, vous savez ouvrir une session MCP, appeler un outil de connecteur (par session ou par appel direct) et lister le registre. Chaque route citée existe dans crates/forge-api/src/router.rs et chaque chiffre vient d'une commande que vous pouvez relancer.

Le principe

Une source de données (API publique d'une institution, service auto-hébergé) est décrite par un fichier YAML de connecteur dans connectors/. Au démarrage, forge-api charge ces fichiers dans un registre ; chaque outil déclaré devient un outil MCP nommé {id-du-connecteur}.{outil} (exemple : data-europa.search_datasets). Le client n'a pas à connaître l'API amont : il appelle l'outil, la plateforme exécute la requête et rend le résultat en JSON.

Mesures reproductibles :

Les deux nombres sont distincts : le registre exécutable (les YAML) et le catalogue business (une liste de fiches de serveurs, voir le chapitre « Routes du catalogue métier »). Ne les confondez pas.

Appeler un connecteur

Deux chemins authentifiés mènent au même registre. Il faut un jeton (Swagger, section Authentification) et l'adresse de votre API : <hote-api> désigne le nom d'hôte de l'API, sans schéma (app.<domaine> derrière le nom public, voir Diagnostics et signalement). Sur un poste de développement, écrivez http://localhost:3000 à la place de https://<hote-api>.

1. Transport MCP (JSON-RPC, session). Ouvrez une session avec initialize, puis appelez tools/call en passant l'en-tête Mcp-Session-Id reçu :

# 1. ouvrir la session (l'identifiant de session revient dans l'en-tête de réponse)
curl -i -X POST "https://<hote-api>/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"mon-client","version":"1.0.0"}}}'

# 2. appeler un outil de connecteur
curl -X POST "https://<hote-api>/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Mcp-Session-Id: <session-id>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"data-europa.search_datasets","arguments":{"q":"energie","limit":5}}}'

La forme des réponses (result.type, result.content, error.code) est décrite dans Routes MCP.

2. Appel direct, sans session. POST /api/v1/mcp/catalog-business/tools/call prend {server, tool, args} et exécute l'outil dans le registre :

curl -X POST "https://<hote-api>/api/v1/mcp/catalog-business/tools/call" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"server":"data-europa","tool":"search_datasets","args":{"q":"energie","limit":5}}'

La réponse est {"success": true, "server": ..., "tool": ..., "result": ...} en cas de succès, ou {"success": false, "error": ...} (statut HTTP 200) si le connecteur est absent ou si l'exécution échoue. Un serveur absent de la liste des serveurs autorisés est refusé avant même la recherche dans le registre, par un 403 de corps {"error": {"code": "FORBIDDEN", ...}} dont le message dit « hors du plan ou non conforme EU ». Cette liste ne dépend pas du locataire (voir Connecteurs MCP).

Pour lister ce que le registre contient :

curl "https://<hote-api>/api/v1/mcp/catalogue" -H "Authorization: Bearer <token>"

La réponse est {"catalogue": [...], "total": N} ; chaque entrée porte l'id, le display_name et le bloc compliance (résidence des données, auto-hébergé, RGPD, licence, Gaia-X).

Sources européennes disponibles

Des connecteurs de sources publiques européennes existent dans connectors/ : eurlex, eurostat, cordis, openaire, europeana, ecb-data, europe-pmc, data-europa. Un méta-moteur de recherche auto-hébergé, searxng, déclare les outils query, config et health.

Ce qui n'existe pas : il n'y a pas de connecteur dédié aux sites de l'EDPB, de la CURIA, de l'EBA ou de l'ESMA. Les sources ci-dessus sont celles que le dépôt livre ; toute autre source passe par l'ajout d'un fichier YAML de connecteur.

Garde-fous réellement en place

• Authentification : les deux chemins exigent un jeton (Authorization: Bearer ou cookie jwt). Une session MCP est liée à l'utilisateur qui l'a ouverte.
• Conformité UE : chaque appel d'outil passe par un point d'étranglement de conformité avant l'exécution (is_server_allowed dans forge-core).
• Plafond amont : le champ rate_limit_per_min du YAML d'un connecteur plafonne les appels sortants vers la source.
• Secrets : les identifiants d'un locataire sont chiffrés au repos (AES-256-GCM) et résolus à la requête ; ils ne sont jamais renvoyés en clair.
• Inventaire logiciel : le SBOM CycloneDX du binaire servi est public sur GET /.well-known/sbom (hors préfixe /api/v1).
• Analyse d'images : l'analyse Trivy des images est exécutée en CI (workflow de CI du dépôt), pas au moment d'un appel d'API.

Ce qui est prévu, et ce qui est retiré

Voir aussi

• Routes MCP : transport Streamable HTTP, sessions et méthodes JSON-RPC détaillées
• Routes du catalogue métier : lecture opérationnelle et cycle de vie prévu
• Documentation Swagger : contrat OpenAPI, obtention du jeton et limites de débit
• Connecter Odoo à la passerelle MCP : un connecteur qui exige les identifiants du locataire, de leur enregistrement au premier appel
• Gestion des erreurs : lire un code d'erreur de l'API ou du transport MCP
• Connecteurs MCP : connecteurs décrits dans ce livre et sources publiques de l'UE
• Créer votre premier connecteur MCP : ajouter une source par un fichier YAML de connecteur