MCP 服务器

Setherion 有一个 MCP 服务器，这是 AI 助手使用其他服务的标准方式。如果你只想在 Claude、ChatGPT、Cursor 或 VS Code 中使用它，请按照 MCP：连接 AI 助手操作。本页面适用于构建你自己的客户端。

这个服务器是换一种说法的 API。每个工具都是对本参考中同名端点的一次调用，使用调用者自己的凭据，所以服务器永远不能做 API 做不到的事。

传输方式

• Streamable HTTP，无状态：把每条消息作为一条 JSON-RPC 2.0 消息，放在 POST 的请求体中发送。没有会话，也没有什么可以恢复。
• 协议版本 2025-06-18 和 2025-03-26：如果你请求的版本是其中之一，initialize 会用该版本回答，否则用 2025-06-18 回答。initialize 之后，在 MCP-Protocol-Version 标头中发送版本。不同的值会被 400 拒绝。
• 只有工具：服务器不提供资源或提示词，也不会主动发送消息。
• 每个请求一条消息：批量请求会被 400 拒绝。
• GET 和 DELETE 会用 405 和 Allow: POST 回答。
• Origin：来自浏览器页面的请求必须来自 https://www.setherion.com。任何其他 Origin 都会得到 403。来自程序的请求不带 Origin，并且是允许的。

请保留地址中的 www。不带它的地址会重定向，而重定向会丢掉凭据。

身份验证

在 Authorization 标头中发送凭据。以下任何一种都可以：

• API 密钥：Authorization: Bearer sth_...。见身份验证。
• OAuth 访问令牌，以 sto_ 开头，只为这个端点签发，不适用于其他端点。见本参考中的 OAuth 登录页面。

如果请求没有凭据，或者凭据有误、已过期或已撤销，会得到 401，并附带登录位置的指引：

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

没有凭据的客户端会跟随 resource_metadata 找到登录入口。令牌只在这个端点上有效：本参考中的 REST 端点使用 API 密钥。

方法

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

工具

instruction 会作为修改的 prompt 发送，最多 4,000 个字符。way 是 easy 或 native。offset 是 0 或更大的整数，也可以作为文本发送。edit_project 不接受模型：它以 auto 运行。

tools/list 会给出每个工具的 title、description、inputSchema 和 annotations。读取类工具标有 readOnlyHint: true，publish_project 标为幂等。

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

工具的结果

工具会以其端点的 JSON 作答，对每种客户端都提供两种形式：

{
  "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。它包含列出你的应用中描述的各个条目。）

当端点拒绝请求时，isError 为 true，structuredContent 会被省略，content 只包含端点的 error 句子，供模型阅读。以 ok: false 结束的修改，在这个意义上也算错误。

较长的修改

一次修改需要几分钟。发送带有 Accept: text/event-stream 的请求，答案就会以流的形式返回：

• 服务器每 10 秒发送一个 notifications/progress 事件，progress 设为到目前为止的秒数，消息为 Still editing, 30s so far，前提是你把 progressToken 放在了 params._meta 中。没有令牌时，它会发送一行注释，: still editing。两者都能让连接保持活动，并让客户端重置它的超时。
• 最后一个事件是工具的结果，以 event: message 的形式，JSON-RPC 响应放在 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}}

没有那个 Accept 标头时，请求会保持打开，并用一个 JSON 对象回答。

四分钟后仍在运行的修改

edit_project 最多等待大约四分钟，因为有些助手会放弃一个安静了五分钟的工具。到那时仍在工作的修改会以 ok: true 和 status: "running" 及它的 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\"."
}

修改会在 Setherion 中继续进行。调用 edit_status，带上 project_id 和 run_id，大约每分钟一次。它的回答与跟进修改进度中相同，直到 status 变为 done。

错误

工具自身的拒绝，比如找不到应用或达到了限制，是带有 isError: true 的工具结果。它们的句子就是错误与限制中列出的那些。