Serveur MCP · Documentation Ephemeral

Ephemeral propose un serveur Model Context Protocol (MCP) : des agents d’IA comme Claude, ChatGPT et les agents de votre éditeur peuvent démarrer des exécutions, attendre les résultats et lire vos workflows directement. Les mêmes clés d’API, rôles, budgets et validations que pour l’API REST s’appliquent. Ils peuvent aussi enregistrer et supprimer des workflows, gérer des planifications et lister vos fichiers : un agent peut ainsi mettre en place une tâche récurrente de bout en bout.

Se connecter avec OAuth

Les clients qui prennent en charge l’autorisation MCP n’ont besoin que de l’URL https://app.ephemer.al/mcp. Le client découvre la connexion d’Ephemeral grâce à la réponse 401 du serveur et à ses métadonnées de ressource protégée, s’enregistre, puis ouvre une page où vous vous connectez, choisissez une organisation et approuvez. Il conserve ensuite un jeton d’accès valable une heure et un jeton d’actualisation : on ne vous redemande rien tant que vous ne révoquez pas l’accès.

L’accès vaut pour l’organisation que vous choisissez, avec le rôle que vous approuvez : member ou admin. Seuls les propriétaires et administrateurs de l’organisation peuvent accorder admin, et le rôle de membre suffit pour tout, sauf créer, modifier ou supprimer des planifications, qui exige admin.
Les jetons ne fonctionnent que pour l’API d’Ephemeral (https://app.ephemer.al), jamais pour d’autres services.
Consultez ou révoquez chaque application connectée sous « Applications autorisées », sur la page de votre compte.
Les métadonnées du serveur d’autorisation se trouvent à l’adresse https://ephemer.al/.well-known/oauth-authorization-server. Les clients doivent utiliser PKCE (S256).

Une installation auto-hébergée n’accepte que les clés d’API.

Se connecter avec une clé d’API

Créez une clé d’API sous Clés dans le tableau de bord. Une clé de membre couvre les exécutions, les workflows et les fichiers ; utilisez une clé d’administrateur si l’agent doit aussi créer, modifier ou supprimer des planifications. Le serveur se trouve à l’adresse https://app.ephemer.al/mcp et utilise le transport Streamable HTTP ; chaque requête porte la clé comme jeton porteur.

Claude Code

Ajoutez le serveur une fois ; il est ensuite disponible dans toutes les sessions.

Terminal

claude mcp add --transport http ephemeral https://app.ephemer.al/mcp \
  --header "Authorization: Bearer $EPHEMERAL_API_KEY"

Cursor, VS Code et autres clients compatibles HTTP

La plupart des clients acceptent un serveur distant avec des en-têtes dans leurs réglages MCP :

JSON

{
  "mcpServers": {
    "ephemeral": {
      "url": "https://app.ephemer.al/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Claude Desktop

Claude Desktop démarre les serveurs locaux depuis son fichier de configuration (claude_desktop_config.json). Le pont mcp-remote le relie à un serveur distant et transmet l’en-tête :

JSON

{
  "mcpServers": {
    "ephemeral": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.ephemer.al/mcp", "--header", "Authorization:${EPHEMERAL_AUTH}"],
      "env": { "EPHEMERAL_AUTH": "Bearer YOUR_API_KEY" }
    }
  }
}

Une installation auto-hébergée sert le même point d’accès à l’URL de son moteur, par exemple https://ephemeral.example.com/mcp, avec une clé de cette installation.

Outils

Chaque outil a un schéma d’entrée, que les clients montrent au modèle, et renvoie du texte et du contenu structuré. Les échecs que l’API REST signale comme des erreurs reviennent comme des erreurs d’outil avec le même message.

Outil	Ce qu’il fait
`create_run`	Démarre une exécution à partir d’un prompt ou d’un workflow enregistré, avec en option entrée, modèle, fichiers, connexions, accès web, shell, délai, plafond de coût et zéro rétention des données. Renvoie l’exécution en file d’attente. Avec idempotency_key, un nouvel essai est sans risque.
`get_run`	Lit une exécution : statut, sortie, erreur, coût et si la facturation est encore en attente. Tant que la facturation est en attente, cost_micros est provisoire et généralement supérieur au coût final, et le résultat indique cost_final: false ; ne citez le coût que lorsque cost_final vaut true.
`wait_for_run`	Attend jusqu’à 60 secondes qu’une exécution se termine et la renvoie. Rappelez-le si l’exécution est toujours en cours. Une fois l’exécution terminée, il attend aussi que la facturation soit réglée, de sorte que le coût renvoyé soit final (cost_final: true) ; si le délai expire avant, le coût est provisoire.
`list_runs`	Liste les exécutions, les plus récentes d’abord, avec filtre de statut et curseur.
`cancel_run`	Annule une exécution qui n’est pas terminée.
`list_workflows`	Liste les workflows enregistrés avec leur description, input_schema et output_schema, pour qu’un agent voie ce que chacun attend et renvoie sans lire son prompt.
`get_workflow`	Lit la définition d’un workflow, sans identifiants.
`list_models`	Recherche des modèles. Renvoie une liste compacte (id, nom, longueur de contexte, prix d’entrée et de sortie par million de jetons, rétention zéro des données) et le total. Arguments : query (partie de l’id ou du nom, sans distinction de casse), limit (25 par défaut, 100 au maximum), zero_data_retention (uniquement les modèles qui la prennent en charge) et model (tous les détails d’un modèle).
`list_connections`	Les connexions enregistrées qu’une exécution peut utiliser, sans URL ni secrets.
`save_workflow`	Crée un workflow ou remplace celui du même nom : prompt, modèle, fichiers, connexions, accès web, shell, délai et zéro rétention des données. Les connexions sont uniquement des références à des connexions enregistrées. Accepte aussi une description et des JSON Schemas pour l’entrée et la sortie.
`delete_workflow`	Supprime un workflow enregistré.
`list_schedules`	Liste les planifications, éventuellement pour un seul workflow, avec le prochain démarrage et le dernier résultat.
`get_schedule`	Lit une planification.
`create_schedule`	Démarre un workflow enregistré selon un calendrier cron et un fuseau horaire, avec entrée et plafond de coût en option. Exige une clé d’administrateur.
`update_schedule`	Modifie une planification, ou la met en pause et la reprend avec enabled. Exige une clé d’administrateur.
`delete_schedule`	Supprime une planification. Exige une clé d’administrateur.
`preview_schedule`	Vérifie une expression cron et renvoie les cinq prochains démarrages, sans rien enregistrer.
`run_schedule`	Démarre dès maintenant le workflow d’une planification et renvoie l’exécution en file d’attente.
`list_files`	Liste les fichiers enregistrés dans l’organisation (lecture seule).

Essayer

Le point d’accès reçoit des messages JSON-RPC 2.0 par POST. Le client s’en charge d’ordinaire ; avec curl, un appel ressemble à ceci :

Terminal

curl -sS https://app.ephemer.al/mcp \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_run","arguments":{"prompt":"Summarize https://example.com","web":true,"max_cost_micros":200000}}}'

Enregistrer un workflow et le planifier

Un agent peut transformer une tâche en travail récurrent en deux appels. D’abord save_workflow, avec ces arguments :

JSON

{
  "name": "weekly-report",
  "prompt": "Summarize last week's support tickets from the helpdesk connection and list the three biggest themes.",
  "connections": { "helpdesk": { "ref": "helpdesk", "allowed_methods": ["GET"] } },
  "timeout_seconds": 600
}

Puis create_schedule (clé d’administrateur), ici chaque lundi à 09:00 à Madrid ; preview_schedule montre d’abord les prochains démarrages :

JSON

{
  "workflow": "weekly-report",
  "cron": "0 9 * * 1",
  "timezone": "Europe/Madrid",
  "max_cost_micros": 500000
}

Rôles

La plupart des outils sont des opérations qu’une clé de membre peut déjà effectuer dans l’API REST, et les outils de planification suivent la même règle que l’API REST : lire, prévisualiser et lancer une planification tout de suite ne demande qu’une clé de membre, tandis que create_schedule, update_schedule et delete_schedule exigent une clé d’administrateur ou de propriétaire et répondent sinon par une erreur d’outil (statut 403). Aucun outil ne crée de clés, ne modifie de connexions ni ne gère la facturation. La clé détermine aussi l’organisation : les exécutions lui sont facturées et apparaissent dans son historique.

Sécurité

Rien ne s’exécute sans clé. Tout le monde peut initialiser et lister les outils, déjà publics ; chaque appel d’outil exige une clé valide et reçoit 401 sans elle.
Les jetons d’accès OAuth expirent au bout d’une heure, sont limités à une organisation et au rôle approuvé, et peuvent être révoqués à tout moment depuis la page de votre compte.
Les budgets s’appliquent. Chaque exécution a un plafond de coût, issu de max_cost_micros ou de la valeur par défaut de l’organisation, et les mêmes contrôles de solde que l’API.
Les connexions sont des références enregistrées. Un agent ne peut nommer qu’une connexion enregistrée par votre organisation, et peut la restreindre avec allowed_methods (par exemple GET uniquement) ou allowed_tools. Il ne peut jamais fournir d’URL ni d’identifiants.
La zéro rétention des données est disponible par exécution. La sortie d’une telle exécution est libérée à sa première lecture.
Seul POST est accepté. Il n’y a ni session ni message émis par le serveur.

Protocole

Les versions de protocole 2025-11-25, 2025-06-18 et 2025-03-26 sont prises en charge ; le serveur répond avec la version demandée par le client. GET et DELETE renvoient 405. Un document de découverte est publié à l’adresse /.well-known/mcp/server-card.json.