Outils IA StormeoOS — `POST /api/mcp/execute`

StormeoOS expose ses données d'agence sous forme d'outils appelables par un agent IA. C'est le pendant « StormeoOS comme serveur » des intégrations MCP : votre agent lit le manifeste, choisit un outil, et l'appelle avec des arguments JSON.

Découverte

GET https://beta.stormeo.io/.well-known/mcp.json

Le manifeste décrit le serveur (nom, version), l'URL d'exécution (/api/mcp/execute), les modes d'auth acceptés (x-api-key ou bearer/session) et la liste des outils avec leurs paramètres.

⚠️ Contrat HTTP simple, pas JSON-RPC. Cette surface accepte { tool, arguments } en POST — elle n'implémente pas (encore) la négociation JSON-RPC du protocole MCP (initialize, tools/list, tools/call). Un client MCP générique type Claude Desktop nécessite un petit adaptateur HTTP.

Authentification

Deux modes :

Mode	Usage	Scopes
Clé API publique `spk_*` (header `x-api-key`)	Agents et intégrations externes	Scopes de la clé, vérifiés par outil
Session StormeoOS	Appels depuis l'app (widgets IA internes)	Accès complet (`*`) dans le périmètre de l'agence

Les clés spk_* se génèrent depuis Compte > Intégrations > API publique — voir l'authentification Public API. Le rate limiting per-clé s'applique.

Contrat d'appel

bash

curl -X POST \
  -H "x-api-key: spk_..." \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_clients", "arguments": {"search": "acme", "limit": 10}}' \
  https://beta.stormeo.io/api/mcp/execute

Réponse :

json

{
  "content": [
    { "id": 42, "name": "Acme SARL", "email": "contact@acme.fr", "phone": null, "status": "active" }
  ],
  "isError": false
}

En cas d'erreur outil (paramètre manquant, ressource introuvable), la réponse reste 200 avec isError: true et un message dans content. Les erreurs d'auth/scope suivent les codes de l'API publique (401, 403 PERMISSION_DENIED).

Outils disponibles (10)

Outil	Scope requis	Arguments	Description
`list_clients`	`clients:read`	`search?`, `limit?`	Liste les clients (recherche nom/email)
`get_client`	`clients:read`	`id`	Détail d'un client
`list_projects`	`clients:read`	`status?`, `limit?`	Liste les projets
`list_tickets`	`tickets:read`	`status?`, `priority?`, `limit?`	Liste les tickets (tri `createdAt DESC`)
`create_ticket`	`tickets:write`	`subject`, `clientId`, …	Crée un ticket
`list_invoices`	`invoices:read`	`limit?`	Liste les factures
`get_dashboard_stats`	`clients:read`	—	Statistiques agrégées de l'agence
`list_websites`	`websites:read`	`limit?`	Liste les sites web
`search_contacts`	`contacts:read`	`search`, `limit?`	Recherche de contacts
`list_services`	`clients:read`	`limit?`	Liste les services

Notes :

limit est plafonné à 100 (défaut 20).
Toutes les lectures sont cloisonnées à votre agence — comme partout ailleurs, un ID d'une autre agence répond comme s'il n'existait pas.
create_ticket est aujourd'hui le seul outil mutant ; il exige tickets:write.

Quand utiliser quoi

Besoin	Surface
Agent IA qui lit/écrit les données StormeoOS	Ces outils (`/api/mcp/execute`)
Intégration applicative classique (CRUD complet, webhooks)	API publique REST
Agent IA qui inspecte un site WordPress connecté	Serveur MCP natif du site
Modifier un site WordPress/PrestaShop connecté	Workflow HITL (via l'UI StormeoOS)

Outils IA StormeoOS — POST /api/mcp/execute ​

Découverte ​

Authentification ​

Contrat d'appel ​