Servidor MCP

Setherion tiene un servidor MCP, la forma estándar en que los asistentes de IA usan otros servicios. Si solo quieres usarlo desde Claude, ChatGPT, Cursor o VS Code, sigue MCP: conecta un asistente de IA. Esta página es para crear tu propio cliente.

El servidor es la API con otra voz. Cada herramienta es una llamada al endpoint del mismo nombre de esta referencia, hecha con la propia credencial de quien llama, así que el servidor nunca puede hacer más de lo que puede hacer la API.

Transporte

• Streamable HTTP, sin estado. Envía cada mensaje como un único mensaje JSON-RPC 2.0 en el cuerpo de un POST. No hay sesiones ni nada que reanudar.
• Versiones de protocolo 2025-06-18 y 2025-03-26. initialize responde con la versión que pediste si es una de estas, y con 2025-06-18 si no lo es. Después de initialize, envía la versión en la cabecera MCP-Protocol-Version. Un valor distinto se rechaza con 400.
• Solo herramientas. El servidor no ofrece recursos ni prompts, y no envía mensajes por su cuenta.
• Un mensaje por petición. Un lote se rechaza con 400.
• GET y DELETE responden 405 con Allow: POST.
• Origin. Una petición desde una página de un navegador debe venir de https://www.setherion.com. Cualquier otro Origin responde 403. Las peticiones de programas no llevan ninguno y se permiten.

Mantén el www en la dirección. La dirección sin él redirige, y una redirección pierde la credencial.

Autenticación

Envía una credencial en la cabecera Authorization. Sirve cualquiera de las dos:

• Una clave de API: Authorization: Bearer sth_.... Consulta Autenticación.
• Un token de acceso OAuth, que empieza por sto_, emitido para este endpoint y para ningún otro. Consulta la página de inicio de sesión con OAuth de esta referencia.

Una petición sin ninguna de las dos, o con una credencial incorrecta, caducada o revocada, responde 401 con una indicación de dónde iniciar sesión:

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 cliente sin credenciales sigue resource_metadata para encontrar el inicio de sesión. Los tokens funcionan solo en este endpoint: los endpoints REST de esta referencia aceptan una clave 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" }'

Herramientas

instruction se envía como el prompt de la edición, hasta 4000 caracteres. way es easy o native. offset es un número entero, 0 o más, y puede enviarse como texto. edit_project no admite un modelo: se ejecuta con auto.

tools/list da el title, la description, el inputSchema y las annotations de cada herramienta. Las herramientas de lectura están marcadas con readOnlyHint: true, y publish_project está 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" } } }'

El resultado de una herramienta

Una herramienta responde con el JSON de su endpoint, en dos 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 aparece abreviado aquí. Tiene las entradas descritas en Lista tus aplicaciones.)

Cuando el endpoint rechaza la petición, isError es true, structuredContent se omite y content contiene solo la frase error del endpoint, para que la lea el modelo. Una edición que termina con ok: false también es un error en este sentido.

Ediciones largas

Una edición tarda minutos. Envía la petición con Accept: text/event-stream y la respuesta llega en flujo:

• Cada 10 segundos el servidor envía un evento notifications/progress, con progress fijado en los segundos transcurridos y el mensaje Still editing, 30s so far, cuando pones un progressToken en params._meta. Sin token envía una línea de comentario, : still editing. Cualquiera de las dos mantiene viva la conexión y permite que un cliente reinicie su tiempo de espera.
• El último evento es el resultado de la herramienta, como event: message con la respuesta JSON-RPC en 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}}

Sin esa cabecera Accept, la petición se queda abierta y responde con un único objeto JSON.

Una edición que sigue en marcha después de cuatro minutos

edit_project espera unos cuatro minutos como máximo, porque algunos asistentes abandonan una herramienta que lleva callada cinco. Una edición que sigue trabajando entonces responde ok: true con status: "running" y su 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 edición continúa en Setherion. Llama a edit_status con project_id y run_id cada minuto más o menos. Responde como en Seguir una edición, hasta que status sea done.

Errores

Los rechazos de las propias herramientas, como una aplicación que no se encuentra o un límite que se alcanzó, son resultados de herramienta con isError: true. Sus frases son las que aparecen en Errores y límites.