Server MCP

Setherion ha un server MCP, il modo standard in cui gli assistenti IA usano altri servizi. Se vuoi usarlo solo da Claude, ChatGPT, Cursor o VS Code, segui MCP: collegare un assistente IA. Questa pagina è per chi crea il proprio client.

Il server è l’API con un’altra voce. Ogni strumento è una chiamata all’endpoint con lo stesso nome in questo riferimento, fatta con la credenziale di chi chiama, quindi il server non può mai fare più di quanto possa fare l’API.

Trasporto

• Streamable HTTP, senza stato. Invia ogni messaggio come un unico messaggio JSON-RPC 2.0 nel corpo di una POST. Non ci sono sessioni e niente da riprendere.
• Versioni del protocollo 2025-06-18 e 2025-03-26. initialize risponde con la versione che hai chiesto se è una di queste, e con 2025-06-18 in caso contrario. Dopo initialize, invia la versione nell’header MCP-Protocol-Version. Un valore diverso viene rifiutato con 400.
• Solo strumenti. Il server non offre risorse né prompt, e non invia messaggi propri.
• Un messaggio per richiesta. Un batch viene rifiutato con 400.
• GET e DELETE rispondono 405 con Allow: POST.
• Origin. Una richiesta da una pagina del browser deve provenire da https://www.setherion.com. Qualsiasi altro Origin risponde 403. Le richieste dei programmi non ne hanno uno e sono consentite.

Tieni il www nell’indirizzo. L’indirizzo senza fa un reindirizzamento, e un reindirizzamento perde la credenziale.

Autenticazione

Invia una credenziale nell’header Authorization. Va bene una qualsiasi delle due:

• Una chiave API: Authorization: Bearer sth_.... Vedi Autenticazione.
• Un token di accesso OAuth, che inizia con sto_, emesso per questo endpoint e per nessun altro. Vedi la pagina di accesso con OAuth di questo riferimento.

Una richiesta senza nessuna delle due, o con una credenziale sbagliata, scaduta o revocata, risponde 401 con un’indicazione su dove accedere:

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 senza credenziali segue resource_metadata per trovare l’accesso. I token funzionano solo su questo endpoint: gli endpoint REST di questo riferimento accettano una chiave API.

Metodi

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

Strumenti

instruction viene inviata come prompt della modifica, fino a 4.000 caratteri. way è easy o native. offset è un numero intero, 0 o più, e può essere inviato come testo. edit_project non accetta un modello: funziona con auto.

tools/list dà title, description, inputSchema e annotations di ogni strumento. Gli strumenti di lettura sono contrassegnati con readOnlyHint: true, e publish_project è contrassegnato come idempotente.

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

Il risultato di uno strumento

Uno strumento risponde con il JSON del suo endpoint, in due forme per ogni tipo di 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 qui è abbreviato. Ha le voci descritte in Elencare le tue app.)

Quando l’endpoint rifiuta, isError è true, structuredContent viene omesso e content contiene soltanto la frase error dell’endpoint, da leggere per il modello. Anche una modifica che termina con ok: false è un errore in questo senso.

Modifiche lunghe

Una modifica richiede minuti. Invia la richiesta con Accept: text/event-stream e la risposta arriva in streaming:

• Ogni 10 secondi il server invia un evento notifications/progress, con progress impostato sui secondi trascorsi e il messaggio Still editing, 30s so far, quando metti un progressToken in params._meta. Senza un token invia una riga di commento, : still editing. Entrambi mantengono viva la connessione e permettono a un client di azzerare il suo timeout.
• L’ultimo evento è il risultato dello strumento, come event: message con la risposta JSON-RPC 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}}

Senza quell’header Accept la richiesta resta aperta e risponde con un solo oggetto JSON.

Una modifica ancora in corso dopo quattro minuti

edit_project aspetta al massimo circa quattro minuti, perché alcuni assistenti rinunciano a uno strumento che è rimasto in silenzio per cinque. Una modifica che sta ancora lavorando a quel punto risponde ok: true con status: "running" e il suo 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 modifica prosegue in Setherion. Chiama edit_status con project_id e run_id ogni minuto circa. Risponde come in Seguire una modifica, finché status non è done.

Errori

I rifiuti degli strumenti stessi, come un’app che non viene trovata o un limite raggiunto, sono risultati di strumento con isError: true. Le loro frasi sono quelle elencate in Errori e limiti.