🔌 Utiliser le bloc MCP dans Celestory

Le bloc MCP de Celestory permet à vos histoires d'appeler les outils de n'importe quel serveur MCP (Model Context Protocol) : lire et écrire des données, interroger un service externe, déclencher des actions… Une seule configuration (une URL) suffit pour découvrir automatiquement tous les outils disponibles d'un serveur, avec leurs arguments typés.

⚠️ Baserow, Airtable, Zapier et Make (Integromat) ont déjà leur propre bloc dédié dans Celestory, plus simple à configurer. N'utilisez le bloc MCP générique que pour un service qui n'a pas de bloc natif.

1. 🤖 C'est quoi MCP ?

MCP (Model Context Protocol) est un standard ouvert qui permet à une application de découvrir et d'appeler les « outils » d'un service externe, de façon uniforme.

• Un serveur MCP expose des outils : par exemple list_rows (lister des lignes), send_message (envoyer un message)…
• Un client MCP appelle ces outils : c'est le rôle du bloc MCP de Celestory.

2. ⚠️ Les deux conditions pour qu'un service fonctionne

Votre histoire s'exécute dans le navigateur (éditeur ou histoire publiée). Deux conditions doivent être remplies pour qu'un serveur MCP soit joignable depuis le bloc — si l'une des deux manque, ça ne marchera pas, quoi que vous fassiez côté Celestory :

Condition 1 : le serveur autorise votre domaine (CORS)

Le navigateur bloque par défaut tout appel vers un autre domaine. Le serveur MCP doit explicitement l'autoriser via des en-têtes CORS (Access-Control-Allow-Origin). C'est une décision qui appartient à l'éditeur du service, pas à Celestory. Si vous héberge vous-même le serveur (auto-hébergé), c'est vous qui contrôlez cette configuration.

Condition 2 : une authentification par jeton statique (pas d'OAuth)

Le bloc MCP de Celestory sait faire deux choses : coller une URL, coller des headers statiques (un objet JSON, ex. {"Authorization": "Bearer …"}). Il ne sait pas dérouler un flow OAuth (popup de connexion, consentement, échange et rafraîchissement de token). Beaucoup de grands éditeurs poussent aujourd'hui leur MCP vers l'OAuth exclusivement — même quand leur CORS est ouvert, la connexion depuis Celestory reste bloquée si l'authentification exige OAuth.

Retenez ceci : CORS ouvert ne veut pas dire que ça marchera. Il faut les deux conditions à la fois.

3. ✅ Services compatibles avec le bloc MCP

Focus gestion de projet : au-delà de la démo, voici comment chaque service s'intègre concrètement dans le pilotage d'un projet.

Auto-hébergé : votre propre serveur MCP fonctionne aussi — vous contrôlez le reverse proxy, donc vous pouvez toujours activer CORS et choisir une authentification par jeton (voir section 6).

La plupart des autres services connus nécessitent un serveur

Figma, Notion, Slack, Stripe, PayPal, Salesforce, HubSpot, Webflow, ClickUp, Jotform, Attio, Netlify… n'acceptent qu'une connexion OAuth (popup de connexion, consentement, refresh de token) que le bloc MCP ne sait pas dérouler dans le navigateur.

Pour ces services, utilisez plutôt le bloc Voltask Webhook. Voltask exécute l'intégration côté serveur : il n'est pas soumis aux contraintes du navigateur (CORS, OAuth). Configurez la connexion au service tiers directement dans Voltask, puis déclenchez-la depuis Celestory via un simple webhook — voir le tutoriel Voltask Webhook.

4. ⚙️ Configurer le bloc MCP dans Celestory

1. Dans le graphe, ajoutez le bloc MCP (catégorie Chatbot).
2. Cliquez sur le point config du bloc et créez une ressource McpConfig.
3. Dans le champ URL, collez l'URL du serveur MCP. Le champ s'agrandit automatiquement pour afficher les URLs longues en entier.
4. Dans le champ Headers (JSON), ajoutez l'authentification requise, par exemple {"Authorization": "Bearer VOTRE_JETON"}.
5. La liste des outils se charge automatiquement si la configuration est correcte. Celestory détecte tout seul le type de transport du serveur (Streamable HTTP moderne ou SSE legacy) : aucun réglage à faire de ce côté.
6. Choisissez un outil : le bloc crée alors une entrée typée par argument de l'outil (survolez le sélecteur pour lire un nom d'outil long en entier).

Le bloc possède aussi ces sorties :

• out (Flux) : la suite de l'histoire si l'appel réussit.
• catch (Flux) : la suite si l'appel échoue.
• result (Objet) : la réponse de l'outil. Si le serveur déclare un schéma de sortie, une sortie typée apparaît en plus pour chaque champ du résultat.
• error (Texte) : le message d'erreur en cas d'échec (pratique pour l'afficher ou le journaliser).

5. 💡 Exemple : lister ses issues GitHub

Scénario : afficher dans l'histoire le nombre d'issues ouvertes d'un dépôt.

1. Créez un jeton d'accès personnel (PAT) sur GitHub (Settings → Developer settings → Personal access tokens), avec le scope repo en lecture.
2. Configurez le bloc MCP : URL https://api.githubcopilot.com/mcp/, headers {"Authorization": "Bearer VOTRE_PAT"}.
3. Choisissez l'outil list_issues (ou équivalent selon la version exposée), renseignez owner et repo sur les entrées générées.
4. Reliez out vers un écran qui affiche le contenu de result, et catch vers un écran qui affiche error.
5. Testez : la liste des issues s'affiche. 🎉

Le principe est identique pour n'importe quel autre serveur MCP qui accepte un jeton statique (Chargebee, votre propre serveur MCP, etc.) : seuls l'URL et le nom des outils changent.

6. 🛡️ CORS sur votre propre serveur MCP (auto-hébergé)

Si vous développez ou hébergez vous-même un serveur MCP (n8n, NocoDB, ou un serveur maison), ajoutez ces en-têtes sur votre reverse proxy (nginx, openresty…) pour la route de votre serveur MCP :

location /votre-route-mcp/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin "https://creator.celestory.io" always;
        add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
        add_header Access-Control-Allow-Headers "content-type, accept, authorization" always;
        add_header Access-Control-Max-Age 86400 always;
        return 204;
    }
    add_header Access-Control-Allow-Origin "https://creator.celestory.io" always;

    proxy_pass http://votre-backend-mcp;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;        # indispensable si votre serveur MCP utilise un flux SSE
    proxy_cache off;
    proxy_read_timeout 24h;
}

Remplacez l'origine par le(s) domaine(s) où votre histoire s'exécute (éditeur et domaine de publication). Access-Control-Allow-Origin n'accepte qu'une seule valeur : pour autoriser plusieurs domaines, faites refléter dynamiquement l'origine par votre proxy (map nginx sur $http_origin).

7. 🚑 Dépannage

• « MCP server unreachable (network error, or the MCP server does not allow this origin via CORS) » → CORS fermé (condition 1) ou réseau : relisez la section 2.
• « MCP legacy SSE: opening the stream failed (HTTP 401/403) » ou une erreur d'appel d'outil qui parle d'authentification → jeton invalide, expiré, ou le serveur exige OAuth (condition 2) : relisez la section 2 et le tableau de la section 3.
• « MCP legacy SSE: opening the stream failed (HTTP 404) » → l'URL est fausse.
• « MCP legacy SSE: no endpoint event received from the server » → l'URL ne pointe pas vers un flux SSE MCP, ou un proxy intermédiaire met le flux en cache (désactivez le buffering).
• « MCP initialize failed » → le serveur a répondu, mais ce n'est pas un serveur MCP valide.
• Un outil renvoie une erreur (sortie error du bloc) → le message vient du serveur MCP lui-même : vérifiez les arguments fournis.

8. 🔐 Bonnes pratiques

• Un jeton d'API n'est jamais qu'un mot de passe : ne le partagez jamais (documentation, captures d'écran, e-mails…).
• Comme votre histoire s'exécute dans le navigateur des joueurs, préférez des jetons à portée limitée (lecture seule, scope restreint à ce dont l'histoire a besoin) plutôt qu'un jeton root/admin.
• Faites tourner vos jetons régulièrement, et immédiatement en cas de doute.

Documentation

Mis à jour le : 20/07/2026