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.
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) |
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", ...}'
권한 매핑
| 권한 | 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 | 내부 서버 오류 |
