> ## 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 서버는 두 가지 인증 방식을 지원합니다: **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 신원 확인             |
| `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     | 내부 서버 오류                                |