Serveur MCP

Setherion dispose d’un serveur MCP, la manière standard dont les assistants d’IA utilisent d’autres services. Si vous voulez seulement l’utiliser depuis Claude, ChatGPT, Cursor ou VS Code, suivez MCP : connecter un assistant d’IA. Cette page s’adresse à celles et ceux qui créent leur propre client.

Le serveur, c’est l’API sous une autre forme. Chaque outil est un appel au point d’accès du même nom dans cette référence, effectué avec les propres identifiants de l’appelant : le serveur ne peut donc jamais faire plus que l’API.

Transport

• Streamable HTTP, sans état. Envoyez chaque message sous la forme d’un message JSON-RPC 2.0 dans le corps d’un POST. Il n’y a pas de sessions et rien à reprendre.
• Versions du protocole 2025-06-18 et 2025-03-26. initialize répond avec la version que vous avez demandée si c’est l’une d’elles, et 2025-06-18 sinon. Après initialize, envoyez la version dans l’en-tête MCP-Protocol-Version. Une valeur différente est refusée avec 400.
• Outils uniquement. Le serveur ne propose ni ressources ni prompts, et n’envoie aucun message de lui-même.
• Un message par requête. Un lot est refusé avec 400.
• GET et DELETE répondent 405 avec Allow: POST.
• Origin. Une requête venant d’une page de navigateur doit provenir de https://www.setherion.com. Tout autre Origin répond 403. Les requêtes de programmes n’en portent aucun et sont acceptées.

Gardez le www dans l’adresse. L’adresse sans lui redirige, et une redirection perd les identifiants.

Authentification

Envoyez des identifiants dans l’en-tête Authorization. L’un ou l’autre convient :

• Une clé d’API : Authorization: Bearer sth_.... Voir Authentification.
• Un jeton d’accès OAuth, qui commence par sto_, émis pour ce point d’accès et aucun autre. Voir la page Connexion avec OAuth de cette référence.

Une requête sans aucun des deux, ou avec des identifiants erronés, expirés ou révoqués, répond 401 avec une indication de l’endroit où se connecter :

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Setherion", resource_metadata="https://www.setherion.com/.well-known/oauth-protected-resource/api/mcp"

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Sign in to Setherion to use this server, or send an API key from your account page as \"Authorization: Bearer sth_...\"."
  }
}

Un client sans identifiants suit resource_metadata pour trouver la connexion. Les jetons ne fonctionnent que sur ce point d’accès : les points d’accès REST de cette référence prennent une clé d’API.

Méthodes

curl -X POST https://www.setherion.com/api/mcp \
  -H "Authorization: Bearer $SETHERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Outils

instruction est envoyé comme le prompt de la modification, jusqu’à 4 000 caractères. way vaut easy ou native. offset est un nombre entier, 0 ou plus, et peut être envoyé sous forme de texte. edit_project ne prend pas de modèle d’IA : il s’exécute sur auto.

tools/list donne pour chaque outil son title, sa description, son inputSchema et ses annotations. Les outils de lecture sont marqués readOnlyHint: true, et publish_project est marqué idempotent.

curl -X POST https://www.setherion.com/api/mcp \
  -H "Authorization: Bearer $SETHERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
        "params": { "name": "list_projects", "arguments": { "query": "coffee" } } }'

Le résultat d’un outil

Un outil répond avec le JSON de son point d’accès, sous deux formes pour tous les types de clients :

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "{ \"ok\": true, \"total\": 1, ... }" }],
    "structuredContent": { "ok": true, "total": 1, "truncated": false, "offset": 0, "nextOffset": null, "projects": [] },
    "isError": false
  }
}

(projects est abrégé ici. Il contient les entrées décrites sur Lister vos applications.)

Quand le point d’accès refuse, isError vaut true, structuredContent est omis, et content contient seulement la phrase error du point d’accès, pour que le modèle d’IA la lise. Une modification qui se termine avec ok: false est aussi une erreur en ce sens.

Modifications longues

Une modification prend plusieurs minutes. Envoyez la requête avec Accept: text/event-stream et la réponse arrive en flux :

• Toutes les 10 secondes, le serveur envoie un événement notifications/progress, avec progress réglé sur le nombre de secondes écoulées et le message Still editing, 30s so far, quand vous placez un progressToken dans params._meta. Sans jeton, il envoie une ligne de commentaire, : still editing. L’un comme l’autre maintient la connexion ouverte et permet à un client de réinitialiser son délai d’attente.
• Le dernier événement est le résultat de l’outil, sous la forme event: message avec la réponse JSON-RPC dans data.

event: message
data: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"t1","progress":10,"message":"Still editing, 10s so far"}}

event: message
data: {"jsonrpc":"2.0","id":3,"result":{"content":[...],"structuredContent":{"ok":true,"runId":"..."},"isError":false}}

Sans cet en-tête Accept, la requête reste ouverte et répond avec un seul objet JSON.

Une modification encore en cours après quatre minutes

edit_project attend environ quatre minutes au maximum, car certains assistants abandonnent un outil resté silencieux pendant cinq. Une modification qui est encore en cours à ce moment-là répond ok: true avec status: "running" et son runId :

{
  "ok": true,
  "status": "running",
  "runId": "b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61",
  "projectId": "7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14",
  "message": "Still editing. It carries on in Setherion without you: do not send it again. Call edit_status with this runId in a minute or so, until it says \"done\"."
}

La modification se poursuit dans Setherion. Appelez edit_status avec project_id et run_id environ chaque minute. Il répond comme dans Suivre une modification, jusqu’à ce que status vaille done.

Erreurs

Les refus venant des outils eux-mêmes, comme une application introuvable ou une limite atteinte, sont des résultats d’outil avec isError: true. Leurs phrases sont celles listées sur Erreurs et limites.