MCP認証 - Caret

Caret MCPサーバーは、2つの認証方式をサポートしています：OAuth 2.0 with PKCE（推奨）およびAPIキー（レガシー）。

OAuth 2.0 with PKCE

ほとんどのMCPクライアント（Claude Desktop、Cursorなど）はOAuthフローを自動的に処理します。このセクションは、カスタムMCPクライアントを開発する開発者向けです。

1. 動的クライアント登録

クライアントを登録して client_id と client_secret を取得します。

curl -X POST "https://api.caret.so/mcp/oauth/register" \
 -H "Content-Type: application/json" \
 -d '{
"client_name": "My MCP Client",
"redirect_uris": ["http://localhost:3000/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "client_secret_post",
"scope": "read offline_access"
}'

レスポンス：

{
  "client_id": "caret_abc123...",
  "client_secret": "secret_xyz...",
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:3000/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_post",
  "scope": "read write offline_access openid profile email"
}

2. 認可リクエスト

ユーザーを認可エンドポイントにリダイレクトします。

GET https://api.caret.so/mcp/oauth/authorize
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={redirect_uri}
  &code_challenge={code_challenge}
  &code_challenge_method=S256
  &state={state}
  &scope=read+offline_access

パラメータ	必須	説明
`response_type`	はい	`code` である必要があります
`client_id`	はい	クライアント登録で取得した値
`redirect_uri`	はい	登録済みのリダイレクトURIと一致する必要があります
`code_challenge`	推奨	PKCEコードチャレンジ（S256）
`code_challenge_method`	チャレンジ使用時	`S256` である必要があります
`state`	推奨	CSRF保護のための不透明な値
`scope`	任意	スペース区切りのスコープ（デフォルト `read`）

ユーザーはGoogleサインインにリダイレクトされ、その後Caretワークスペースの選択を求められます。認可後、ユーザーは code パラメータ付きで redirect_uri にリダイレクトされます。

3. トークン交換

認可コードをトークンに交換します。

curl -X POST "https://api.caret.so/mcp/oauth/token" \ -H
"Content-Type: application/x-www-form-urlencoded" \ -d
"grant_type=authorization_code" \ -d "code={authorization_code}" \ -d
"redirect_uri={redirect_uri}" \ -d "client_id={client_id}" \ -d
"client_secret={client_secret}" \ -d "code_verifier={code_verifier}"

レスポンス：

{
"access_token": "eyJhbGciOiJIUzI1...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "rt_abc123...",
"scope": "read offline_access"
}

4. トークンのリフレッシュ

アクセストークンの有効期限が切れたら、リフレッシュトークンを使用して新しいトークンを取得します。

curl -X POST "https://api.caret.so/mcp/oauth/token" \ -H
"Content-Type: application/x-www-form-urlencoded" \ -d
"grant_type=refresh_token" \ -d "refresh_token={refresh_token}" \ -d
"client_id={client_id}" \ -d "client_secret={client_secret}"

リフレッシュのたびに既存のリフレッシュトークンは無効化され、新しいトークンが発行されます。

スコープ

スコープ	説明
`read`	ノート、ナレッジ、ワークスペース、メンバーへの読み取りアクセス
`write`	書き込みアクセス（将来の利用予定）
`offline_access`	リフレッシュトークンのリクエスト
`openid`	OpenID Connect ID
`profile`	ユーザープロフィール情報
`email`	ユーザーメールアドレス

トークンの有効期間

トークン	有効期間
アクセストークン（JWT）	1時間
リフレッシュトークン	30日
認可コード	10分

APIキー認証

OAuthの代替として、既存のCaret APIキーを使用できます。

curl -X POST "https://api.caret.so/mcp" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", ...}'

APIキーはCaretアプリの 設定 > 開発者 で作成します。詳細は API認証を参照してください。

権限マッピング

権限	MCPツール
`notes` / `read`	`caret_list_notes`, `caret_get_note`, `caret_search_notes`, `caret_search_knowledge`
`users` / `read`	`caret_list_members`
（不要）	`caret_get_workspace`

エラー

エラー	ステータス	説明
`invalid_client`	400/401	不明なクライアントまたは認証に失敗しました
`invalid_grant`	400	認可コードの有効期限切れ、使用済み、またはPKCE検証に失敗しました
`invalid_scope`	400	リクエストされたスコープがサポートされていないか、許可されていません
`invalid_request`	400	パラメータの欠落または不正な形式
`server_error`	500	内部サーバーエラー

​OAuth 2.0 with PKCE

​1. 動的クライアント登録

​2. 認可リクエスト

​3. トークン交換

​4. トークンのリフレッシュ

​スコープ

​トークンの有効期間

​APIキー認証

​権限マッピング

​エラー