MCP 인증 - Caret

Caret MCP 서버는 두 가지 인증 방식을 지원합니다: 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 신원 확인
`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 키 인증

​권한 매핑

​오류