Serwer MCP

Setherion ma serwer MCP, standardowy sposób, w jaki asystenci AI korzystają z innych usług. Jeśli chcesz używać go tylko z Claude, ChatGPT, Cursor lub VS Code, skorzystaj z MCP: podłącz asystenta AI. Ta strona jest dla tych, którzy budują własnego klienta.

Serwer to API innym głosem. Każde narzędzie to wywołanie punktu końcowego o tej samej nazwie w tej dokumentacji, wykonane z własnymi poświadczeniami wywołującego, więc serwer nigdy nie może zrobić więcej niż API.

Transport

• Streamable HTTP, bez stanu. Wysyłaj każdą wiadomość jako jedną wiadomość JSON-RPC 2.0 w treści żądania POST. Nie ma sesji i nie ma czego wznawiać.
• Wersje protokołu 2025-06-18 i 2025-03-26. initialize odpowiada wersją, o którą poprosisz, jeśli jest jedną z tych, a w przeciwnym razie 2025-06-18. Po initialize wysyłaj wersję w nagłówku MCP-Protocol-Version. Inna wartość jest odrzucana z 400.
• Tylko narzędzia. Serwer nie oferuje zasobów ani promptów i nie wysyła własnych wiadomości.
• Jedna wiadomość na żądanie. Paczka wiadomości jest odrzucana z 400.
• GET i DELETE odpowiadają 405 z Allow: POST.
• Origin. Żądanie ze strony w przeglądarce musi pochodzić z https://www.setherion.com. Każdy inny Origin odpowiada 403. Żądania z programów go nie mają i są dozwolone.

Zachowaj www w adresie. Adres bez niego przekierowuje, a przekierowanie gubi poświadczenia.

Uwierzytelnianie

Wyślij poświadczenia w nagłówku Authorization. Działa jedno i drugie:

• Klucz API: Authorization: Bearer sth_.... Zobacz Uwierzytelnianie.
• Token dostępu OAuth, który zaczyna się od sto_, wydany dla tego punktu końcowego i żadnego innego. Zobacz stronę logowania przez OAuth w tej dokumentacji.

Żądanie bez żadnych poświadczeń albo z poświadczeniami błędnymi, wygasłymi lub cofniętymi odpowiada 401 ze wskazaniem, gdzie się zalogować:

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

Klient bez poświadczeń idzie za resource_metadata, aby znaleźć logowanie. Tokeny działają tylko w tym punkcie końcowym: punkty końcowe REST w tej dokumentacji przyjmują klucz API.

Metody

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

Narzędzia

instruction jest wysyłane jako prompt edycji, do 4 000 znaków. way to easy lub native. offset to liczba całkowita, 0 lub więcej, którą można wysłać jako tekst. edit_project nie przyjmuje modelu: działa na auto.

tools/list podaje dla każdego narzędzia title, description, inputSchema i annotations. Narzędzia tylko do odczytu są oznaczone readOnlyHint: true, a publish_project jest oznaczone jako idempotentne.

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

Wynik narzędzia

Narzędzie odpowiada JSON-em swojego punktu końcowego, w dwóch postaciach dla każdego rodzaju klienta:

{
  "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 jest tu skrócone. Ma wpisy opisane na stronie Lista Twoich aplikacji.)

Gdy punkt końcowy odmawia, isError ma wartość true, structuredContent jest pomijane, a content zawiera samo zdanie error punktu końcowego, do przeczytania przez model. Edycja, która kończy się ok: false, jest w tym sensie także błędem.

Długie edycje

Edycja trwa minuty. Wyślij żądanie z Accept: text/event-stream, a odpowiedź będzie strumieniowana:

• Co 10 sekund serwer wysyła zdarzenie notifications/progress, z progress ustawionym na dotychczasowe sekundy i komunikatem Still editing, 30s so far, gdy umieścisz progressToken w params._meta. Bez tokena wysyła wiersz komentarza, : still editing. Jedno i drugie utrzymuje połączenie i pozwala klientowi zresetować limit czasu.
• Ostatnie zdarzenie to wynik narzędzia, jako event: message z odpowiedzią JSON-RPC w 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}}

Bez tego nagłówka Accept żądanie pozostaje otwarte i odpowiada jednym obiektem JSON.

Edycja nadal trwa po czterech minutach

edit_project czeka najwyżej około czterech minut, ponieważ niektórzy asystenci rezygnują z narzędzia, które milczy przez pięć. Edycja, która nadal trwa, odpowiada wtedy ok: true ze status: "running" i swoim 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\"."
}

Edycja trwa dalej w Setherion. Wywołuj edit_status z project_id i run_id mniej więcej co minutę. Odpowiada tak jak w Śledzenie edycji, aż status będzie done.

Błędy

Odmowy samych narzędzi, takie jak nieznaleziona aplikacja albo osiągnięty limit, są wynikami narzędzi z isError: true. Ich zdania są te wymienione na stronie Błędy i limity.