OAuthでログインする

AIアシスタントは、APIキーではなくOAuthでSetherionにログインします。ユーザーがSetherionのページでAllowを押すと、アシスタントがトークンを受け取ります。このページは、自分でクライアントを作る人のための仕様です。Claude、ChatGPT、Cursor、VS Codeを接続したいだけの場合は、MCP：AIアシスタントを接続するに従ってください。

このフローは、MCPの認可仕様（2025-06-18）が求めるOAuth 2.1です。

• 認可コードフローで、PKCE（S256）が常に必須です。
• パブリッククライアントのみで、クライアントシークレットはありません。
• 動的クライアント登録（RFC 7591）なので、クライアントIDをどこかに貼り付ける必要はありません。
• トークンは1つのリソース、つまりMCPエンドポイントに紐づきます（RFC 8707）。

トークンはMCPサーバーでのみ使え、それ以外では使えません。このリファレンスのRESTエンドポイントはAPIキーを使います。

1. ディスカバリー

認証情報なしでMCPエンドポイントにリクエストを送ります。401のWWW-Authenticateヘッダーが、リソースメタデータ（RFC 9728）を指します。

curl https://www.setherion.com/.well-known/oauth-protected-resource/api/mcp

{
  "resource": "https://www.setherion.com/api/mcp",
  "authorization_servers": ["https://www.setherion.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"],
  "resource_name": "Setherion"
}

同じドキュメントが/.well-known/oauth-protected-resourceにもあります。次に、認可サーバーのメタデータ（RFC 8414）を読みます。

curl https://www.setherion.com/.well-known/oauth-authorization-server

{
  "issuer": "https://www.setherion.com",
  "authorization_endpoint": "https://www.setherion.com/oauth/authorize",
  "token_endpoint": "https://www.setherion.com/api/oauth/token",
  "registration_endpoint": "https://www.setherion.com/api/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp"]
}

この2つのドキュメント、登録エンドポイント、トークンエンドポイントは、どのオリジンからのリクエストにも応答する（Access-Control-Allow-Origin: *）ので、ブラウザー上のページのクライアントから呼び出せます。

2. 登録

インストールごとに1回登録します。登録しただけでは何も許可されません。ユーザーがAllowを押す必要があり、コードはここで登録した正確なアドレスにだけ送り返されます。

curl -X POST https://www.setherion.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "My assistant", "redirect_uris": ["http://localhost:8787/callback"] }'

リダイレクトアドレスはhttpsか、このマシンに戻るhttp（localhost、127.0.0.1、[::1]）でなければなりません。フラグメントやユーザー名を含めることはできません。httpsでもhttpでもない唯一のアドレスは、古いCursorアプリ向けのcursor://anysphere.cursor-mcp/oauth/callbackです。

クライアントがどの認証方式を求めても、シークレットなしのパブリッククライアントとして登録され、レスポンスにもそれが示されます。

{
  "client_id": "5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30",
  "client_id_issued_at": 1790000000,
  "client_name": "My assistant",
  "redirect_uris": ["http://localhost:8787/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

ステータスは201です。登録は、ネットワークアドレスごとに1時間あたり20回までに制限されています。

3. ユーザーに確認する

認可エンドポイントを、ユーザーのブラウザーで開きます。これはAPIではなくページです。ユーザーはSetherionにまだログインしていなければログインし、登録した名前と戻り先を確認して、AllowまたはCancelを押します。

https://www.setherion.com/oauth/authorize
  ?response_type=code
  &client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30
  &redirect_uri=http%3A%2F%2Flocalhost%3A8787%2Fcallback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj
  &resource=https%3A%2F%2Fwww.setherion.com%2Fapi%2Fmcp

ベリファイアはA-Z a-z 0-9 - . _ ~の文字を使って43文字から128文字にし、ステップ4まで保持しておきます。

ユーザーは次の内容とともにredirect_uriに戻されます。

• Allowの場合：code、state、iss（Issuer）。
• Cancelの場合：error=access_denied、error_description=The request was declined.、state、iss。
• リクエストに問題があり、クライアントとアドレスが本物だと分かっている場合：error、error_description、state、iss。errorはunsupported_response_type、invalid_request（PKCEがない、またはメソッドがS256ではない）、invalid_target（リソースがMCPエンドポイントではない）のどれかです。

クライアントが不明な場合や、アドレスが登録したものではない場合は、ページがユーザーにそう伝え、どこにも移動させません。そのため、このページを使って、登録していないアドレスにユーザーをリダイレクトすることはできません。

4. コードを交換する

OAuthの仕様どおり、フォームエンコードのフィールドを送ります。同じ名前のJSONも受け付けられます。

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=stc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30 \
  -d redirect_uri=http://localhost:8787/callback \
  -d code_verifier=YOUR_VERIFIER

{
  "access_token": "sto_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "mcp"
}

アクセストークンは、Authorization: Bearer sto_...としてMCPサーバーに送ります。トークンはキャッシュされません。レスポンスにはCache-Control: no-storeが付いています。

5. 更新

アクセストークンの有効期間は1時間です。期限が切れる前、またはMCPサーバーが401を返したときに、リフレッシュトークンを交換します。

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30

レスポンスはステップ4と同じですが、リフレッシュトークンは新しいものになります。古いものは使えなくなるので、毎回新しいものを保存してください。

エラー

トークンエンドポイントのエラーのうち、ステータスが400なのはserver_errorを除くすべてで、本文は{ "error": "...", "error_description": "..." }です。

接続を終了する

ユーザーは、Settings、AI assistants and MCPの順に開いて、アシスタントの接続を解除できます。その接続のすべてのトークン（アクセストークンもリフレッシュトークンも）は、1時間の期限を待たず、次のリクエストからすぐに使えなくなります。接続の一覧表示と終了は、ログイン済みのSetherionのセッションからしかできないので、アシスタントが持っているものでは実行できません。

代わりにAPIキーを使う

固定のヘッダーしか送れないクライアントは、これらをすべて省略して、MCPサーバーにAPIキーを送ることができます。認証を見てください。