MCPサーバー

Setherionには、AIアシスタントがほかのサービスを使うための標準的な方法であるMCPサーバーがあります。Claude、ChatGPT、Cursor、VS Codeから使うだけなら、MCP：AIアシスタントを接続するに従ってください。このページは、独自のクライアントを作る方のためのものです。

このサーバーは、別の語り口で話すAPIです。各ツールは、このリファレンスにある同じ名前のエンドポイントへの呼び出しで、呼び出し元自身の認証情報で行われるので、サーバーがAPIにできる以上のことをすることはありません。

トランスポート

• ステートレスなStreamable HTTP。 すべてのメッセージを、POSTの本文にある1つのJSON-RPC 2.0メッセージとして送ります。セッションはなく、再開するものもありません。
• プロトコルのバージョンは2025-06-18と2025-03-26です。initializeは、要求されたバージョンがこのどちらかならそれを返し、そうでなければ2025-06-18を返します。initializeの後は、MCP-Protocol-Versionヘッダーにバージョンを入れて送ります。異なる値は400で拒否されます。
• ツールのみ。 サーバーはリソースもプロンプトも提供せず、自分からメッセージを送ることもありません。
• 1つのリクエストに1つのメッセージ。 バッチは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を、どの種類のクライアントでも扱えるように2つの形式で返します。

{
  "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として、dataにJSON-RPCのレスポンスが入ります。

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ヘッダーがないと、リクエストは開いたままになり、1つのJSONオブジェクトで応答します。

4分たってもまだ実行中の編集

edit_projectは、最大でも約4分しか待ちません。5分間無音のツールを、あきらめてしまうアシスタントがあるためです。その時点でまだ作業中の編集は、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を付けて、1分ごとを目安に呼び出してください。statusがdoneになるまで、編集の進行状況を追うにあるとおりに応答します。

エラー

アプリが見つからない、上限に達したなど、ツール自身による拒否は、isError: trueのツールの結果です。その文は、エラーと制限に挙げられているものです。