> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caret.so/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP認証

> OAuth 2.0またはAPIキーを使用してCaret MCPサーバーに認証する方法

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` を取得します。

<CodeGroup>
  ```bash curl theme={null}

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

  ```
</CodeGroup>

**レスポンス：**

```json theme={null}
{
  "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. トークン交換

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

<CodeGroup>
  ```bash curl theme={null}

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

  ```
</CodeGroup>

**レスポンス：**

```json theme={null}
{
"access_token": "eyJhbGciOiJIUzI1...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "rt_abc123...",
"scope": "read offline_access"
}
```

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

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

<CodeGroup>
  ```bash curl theme={null}

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

  ```
</CodeGroup>

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

### スコープ

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

### トークンの有効期間

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

## APIキー認証

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

<CodeGroup>
  ```bash curl theme={null}

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

  ```
</CodeGroup>

APIキーはCaretアプリの **設定 > 開発者** で作成します。詳細は [API認証](/api-reference/authentication) を参照してください。

## 権限マッピング

| 権限               | 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     | 内部サーバーエラー                          |