메인 콘텐츠로 건너뛰기
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리프레시 토큰 요청
openidOpenID 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 / readcaret_list_notes, caret_get_note, caret_search_notes, caret_search_knowledge
users / readcaret_list_members
(없음)caret_get_workspace

​
오류

오류상태설명
invalid_client400/401알 수 없는 클라이언트이거나 인증에 실패했습니다
invalid_grant400인가 코드가 만료되었거나 이미 사용되었거나 PKCE 검증에 실패했습니다
invalid_scope400요청한 스코프가 지원되지 않거나 허용되지 않습니다
invalid_request400파라미터가 누락되었거나 형식이 잘못되었습니다
server_error500내부 서버 오류