MCP-Server

Setherion hat einen MCP-Server, den Standardweg, auf dem KI-Assistenten andere Dienste nutzen. Wenn Sie ihn nur von Claude, ChatGPT, Cursor oder VS Code aus nutzen möchten, folgen Sie MCP: einen KI-Assistenten verbinden. Diese Seite ist für den Bau Ihres eigenen Clients.

Der Server ist die API in anderer Stimme. Jedes Tool ist ein Aufruf des gleichnamigen Endpunkts in dieser Referenz, ausgeführt mit den eigenen Zugangsdaten des Aufrufers, sodass der Server nie mehr kann als die API.

Transport

• Streamable HTTP, zustandslos. Senden Sie jede Nachricht als eine JSON-RPC-2.0-Nachricht im Body eines POST. Es gibt keine Sitzungen und nichts, was fortgesetzt werden könnte.
• Protokollversionen 2025-06-18 und 2025-03-26. initialize antwortet mit der Version, nach der Sie gefragt haben, wenn sie eine dieser beiden ist, und sonst mit 2025-06-18. Senden Sie nach initialize die Version im Header MCP-Protocol-Version. Ein abweichender Wert wird mit 400 abgelehnt.
• Nur Tools. Der Server bietet keine Ressourcen oder Prompts und sendet keine eigenen Nachrichten.
• Eine Nachricht pro Anfrage. Ein Batch wird mit 400 abgelehnt.
• GET und DELETE antworten mit 405 und Allow: POST.
• Origin. Eine Anfrage von einer Browserseite muss von https://www.setherion.com kommen. Jeder andere Origin antwortet mit 403. Anfragen von Programmen tragen keinen und sind erlaubt.

Behalten Sie das www in der Adresse bei. Die Adresse ohne es leitet weiter, und eine Weiterleitung verliert die Zugangsdaten.

Authentifizierung

Senden Sie Zugangsdaten im Header Authorization. Beides funktioniert:

• Ein API-Schlüssel: Authorization: Bearer sth_.... Siehe Authentifizierung.
• Ein OAuth-Zugriffstoken, das mit sto_ beginnt und für diesen Endpunkt und keinen anderen ausgestellt wurde. Siehe die Seite zur Anmeldung mit OAuth in dieser Referenz.

Eine Anfrage mit keinem von beiden oder mit Zugangsdaten, die falsch, abgelaufen oder widerrufen sind, antwortet mit 401 und einem Hinweis, wo man sich anmeldet:

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_...\"."
  }
}

Ein Client ohne Zugangsdaten folgt resource_metadata, um die Anmeldung zu finden. Die Tokens funktionieren nur an diesem Endpunkt: Die REST-Endpunkte dieser Referenz nehmen einen API-Schlüssel.

Methoden

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" }'

Tools

instruction wird als prompt der Änderung gesendet, bis zu 4.000 Zeichen. way ist easy oder native. offset ist eine ganze Zahl, 0 oder mehr, und darf als Text gesendet werden. edit_project nimmt kein KI-Modell: Es läuft mit auto.

tools/list liefert für jedes Tool title, description, inputSchema und annotations. Lesende Tools sind mit readOnlyHint: true markiert, und publish_project ist als idempotent markiert.

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" } } }'

Das Ergebnis eines Tools

Ein Tool antwortet mit dem JSON seines Endpunkts, in zwei Formen für jede Art von Client:

{
  "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 ist hier gekürzt. Es enthält die Einträge, die unter Ihre Apps auflisten beschrieben sind.)

Wenn der Endpunkt ablehnt, ist isError true, structuredContent entfällt, und content enthält allein den Satz error des Endpunkts, den das KI-Modell lesen soll. Eine Änderung, die mit ok: false endet, ist in diesem Sinne ebenfalls ein Fehler.

Lange Änderungen

Eine Änderung dauert Minuten. Senden Sie die Anfrage mit Accept: text/event-stream, und die Antwort wird gestreamt:

• Alle 10 Sekunden sendet der Server ein Ereignis notifications/progress, mit progress auf die bisherigen Sekunden gesetzt und der Meldung Still editing, 30s so far, wenn Sie einen progressToken in params._meta angeben. Ohne Token sendet er eine Kommentarzeile, : still editing. Beides hält die Verbindung am Leben und lässt einen Client sein Timeout zurücksetzen.
• Das letzte Ereignis ist das Tool-Ergebnis, als event: message mit der JSON-RPC-Antwort in 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}}

Ohne diesen Header Accept bleibt die Anfrage offen und antwortet mit einem einzigen JSON-Objekt.

Eine Änderung, die nach vier Minuten noch läuft

edit_project wartet höchstens etwa vier Minuten, weil manche Assistenten ein Tool aufgeben, das fünf Minuten lang still war. Eine Änderung, die dann noch arbeitet, antwortet mit ok: true, status: "running" und ihrer 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\"."
}

Die Änderung läuft in Setherion weiter. Rufen Sie edit_status etwa jede Minute mit project_id und run_id auf. Es antwortet wie unter Eine Änderung verfolgen, bis status den Wert done hat.

Fehler

Ablehnungen durch die Tools selbst, etwa eine App, die nicht gefunden wird, oder ein erreichtes Limit, sind Tool-Ergebnisse mit isError: true. Ihre Sätze sind die, die unter Fehler und Limits aufgelistet sind.