Servidor MCP

O Setherion tem um servidor MCP, a forma padrão de os assistentes de IA usarem outros serviços. Se você só quer usá-lo a partir do Claude, do ChatGPT, do Cursor ou do VS Code, siga MCP: conectar um assistente de IA. Esta página é para criar o seu próprio cliente.

O servidor é a API com outra voz. Cada ferramenta é uma chamada ao endpoint de mesmo nome nesta referência, feita com a credencial do próprio autor da chamada, então o servidor nunca pode fazer mais do que a API pode.

Transporte

• Streamable HTTP, sem estado. Envie cada mensagem como uma única mensagem JSON-RPC 2.0 no corpo de um POST. Não há sessões e nada para retomar.
• Versões do protocolo 2025-06-18 e 2025-03-26. initialize responde com a versão que você pediu se for uma destas, e com 2025-06-18 caso contrário. Depois de initialize, envie a versão no header MCP-Protocol-Version. Um valor diferente é recusado com 400.
• Somente ferramentas. O servidor não oferece recursos nem prompts, e não envia mensagens por conta própria.
• Uma mensagem por solicitação. Um lote é recusado com 400.
• GET e DELETE respondem 405 com Allow: POST.
• Origin. Uma solicitação vinda de uma página de navegador precisa vir de https://www.setherion.com. Qualquer outro Origin responde 403. Solicitações vindas de programas não carregam nenhum e são permitidas.

Mantenha o www no endereço. O endereço sem ele redireciona, e um redirecionamento descarta a credencial.

Autenticação

Envie uma credencial no header Authorization. Qualquer uma das duas serve:

• Uma chave de API: Authorization: Bearer sth_.... Veja Autenticação.
• Um token de acesso OAuth, que começa com sto_, emitido para este endpoint e para nenhum outro. Veja a página de login com OAuth desta referência.

Uma solicitação sem nenhuma das duas, ou com uma credencial errada, expirada ou revogada, responde 401 com uma indicação de onde entrar:

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

Um cliente sem credenciais segue resource_metadata para encontrar o login. Os tokens funcionam apenas neste endpoint: os endpoints REST desta referência aceitam uma chave de API.

Métodos

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

Ferramentas

instruction é enviada como o prompt da edição, com até 4.000 caracteres. way é easy ou native. offset é um número inteiro, 0 ou mais, e pode ser enviado como texto. edit_project não aceita um modelo: ele roda em auto.

tools/list informa title, description, inputSchema e annotations de cada ferramenta. As ferramentas de leitura são marcadas com readOnlyHint: true, e publish_project é marcada como 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" } } }'

O resultado de uma ferramenta

Uma ferramenta responde com o JSON do seu endpoint, em duas formas para todo tipo de cliente:

{
  "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á abreviado aqui. Ele tem as entradas descritas em Listar seus apps.)

Quando o endpoint recusa, isError é true, structuredContent é omitido e content traz apenas a frase de error do endpoint, para o modelo ler. Uma edição que termina com ok: false também é um erro nesse sentido.

Edições longas

Uma edição leva minutos. Envie a solicitação com Accept: text/event-stream e a resposta chega em fluxo:

• A cada 10 segundos o servidor envia um evento notifications/progress, com progress definido como os segundos até agora e a mensagem Still editing, 30s so far, quando você coloca um progressToken em params._meta. Sem um token, ele envia uma linha de comentário, : still editing. Qualquer um dos dois mantém a conexão ativa e permite que um cliente reinicie o seu tempo limite.
• O último evento é o resultado da ferramenta, como event: message com a resposta JSON-RPC em 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}}

Sem esse header Accept, a solicitação fica aberta e responde com um único objeto JSON.

Uma edição ainda em andamento depois de quatro minutos

edit_project espera cerca de quatro minutos no máximo, porque alguns assistentes desistem de uma ferramenta que ficou em silêncio por cinco. Uma edição que ainda está trabalhando nesse momento responde ok: true com status: "running" e o seu 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\"."
}

A edição continua no Setherion. Chame edit_status com project_id e run_id a cada minuto, mais ou menos. Ele responde como em Acompanhar uma edição, até que status seja done.

Erros

As recusas das próprias ferramentas, como um app que não foi encontrado ou um limite que foi atingido, são resultados de ferramenta com isError: true. As frases delas são as listadas em Erros e limites.