Serverul MCP

Setherion are un server MCP, felul standard în care asistenții AI folosesc alte servicii. Dacă vrei doar să-l folosești din Claude, ChatGPT, Cursor sau VS Code, urmează MCP: conectează un asistent AI. Pagina aceasta e pentru cine își construiește propriul client.

Serverul este API-ul cu altă voce. Fiecare unealtă este un apel către endpointul cu același nume din această referință, făcut cu credențialul celui care apelează, așa că serverul nu poate face niciodată mai mult decât API-ul.

Transport

• Streamable HTTP, fără stare. Trimite fiecare mesaj ca un singur mesaj JSON-RPC 2.0 în corpul unui POST. Nu există sesiuni și nu e nimic de reluat.
• Versiunile de protocol 2025-06-18 și 2025-03-26. initialize răspunde cu versiunea pe care ai cerut-o dacă e una dintre acestea, și cu 2025-06-18 în caz contrar. După initialize, trimite versiunea în antetul MCP-Protocol-Version. O valoare diferită este refuzată cu 400.
• Doar unelte. Serverul nu oferă resurse sau prompturi și nu trimite mesaje de la sine.
• Un mesaj pe cerere. Un lot este refuzat cu 400.
• GET și DELETE răspund cu 405 și Allow: POST.
• Origin. O cerere dintr-o pagină de browser trebuie să vină de la https://www.setherion.com. Orice alt Origin primește 403. Cererile din programe nu poartă niciunul și sunt acceptate.

Păstrează www în adresă. Adresa fără el face o redirecționare, iar redirecționarea pierde credențialul.

Autentificare

Trimite un credențial în antetul Authorization. Merge oricare dintre ele:

• O cheie API: Authorization: Bearer sth_.... Vezi Autentificare.
• Un token de acces OAuth, care începe cu sto_, emis pentru acest endpoint și pentru niciun altul. Vezi pagina de autentificare OAuth din această referință.

O cerere fără niciuna, sau cu un credențial greșit, expirat ori revocat, primește 401, cu un indiciu despre unde te autentifici:

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 fără credențiale urmează resource_metadata ca să găsească autentificarea. Tokenurile merg doar pe acest endpoint: endpointurile REST din această referință primesc o cheie API.

Metode

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

Unelte

instruction se trimite ca prompt al modificării, până la 4.000 de caractere. way este easy sau native. offset este un număr întreg, 0 sau mai mare, și poate fi trimis ca text. edit_project nu primește un model: rulează pe auto.

tools/list dă pentru fiecare unealtă title, description, inputSchema și annotations. Uneltele care doar citesc sunt marcate cu readOnlyHint: true, iar publish_project este marcată ca 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" } } }'

Rezultatul unei unelte

O unealtă răspunde cu JSON-ul endpointului ei, în două forme, pentru orice fel de 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 este scurtat aici. Are intrările descrise la Listează aplicațiile tale.)

Când endpointul refuză, isError este true, structuredContent lipsește, iar content conține doar propoziția error a endpointului, pe care s-o citească modelul. O modificare care se termină cu ok: false este și ea o eroare în sensul acesta.

Modificări lungi

O modificare durează minute. Trimite cererea cu Accept: text/event-stream și răspunsul vine în flux:

• La fiecare 10 secunde serverul trimite un eveniment notifications/progress, cu progress setat la secundele trecute și mesajul Still editing, 30s so far, dacă ai pus un progressToken în params._meta. Fără token trimite o linie de comentariu, : still editing. Oricare dintre ele ține conexiunea vie și lasă clientul să-și reia cronometrul.
• Ultimul eveniment este rezultatul uneltei, ca event: message, cu răspunsul JSON-RPC în 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}}

Fără antetul Accept, cererea rămâne deschisă și răspunde cu un singur obiect JSON.

O modificare încă în lucru după patru minute

edit_project așteaptă cel mult vreo patru minute, pentru că unii asistenți renunță la o unealtă care tace de cinci. O modificare care încă lucrează atunci răspunde cu ok: true, status: "running" și runId-ul ei:

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

Modificarea merge mai departe în Setherion. Apelează edit_status cu project_id și run_id cam din minut în minut. Răspunde ca la Urmărirea unei modificări, până când status este done.

Erori

Refuzurile venite de la unelte, cum ar fi o aplicație negăsită sau o limită atinsă, sunt rezultate de unealtă cu isError: true. Propozițiile lor sunt cele din Erori și limite.