MCP
Thinkfree Drive는 /mcp 경로에 MCP(Model Context Protocol) 서버를 내장하고 있습니다. AI 클라이언트 — 클로드 앱,
Claude Code, 그 밖의 MCP 클라이언트 — 가 OAuth 2.0 또는 API Key로 연동하면 연결된 계정의 권한으로 Drive 기능을
호출합니다. 일반 사용자(USER) 계정은 파일·폴더·공유 툴을, 관리자(ADMIN) 계정은 계정·API Key 툴을 사용합니다.
서버가 제공하는 툴은 50종으로, 사용자 툴 27종과 관리자 툴 23종입니다.
| 항목 | 내용 |
|---|---|
| 엔드포인트 | tenant 서브도메인의 /mcp, Streamable HTTP. Stateless — Mcp-Session-Id 세션이 없고 initialize 없이 tools/list·tools/call을 단발로 호출합니다. |
| 인증 | Authorization: Bearer replace-with-your-api-key 헤더 한 가지에 OAuth 2.0 액세스 토큰(동적 클라이언트 등록 + 사용자 동의) 또는 API Key 원문(관리자 화면에서 발급하는 불투명 문자열)을 담습니다. 서버는 JWT 형태면 OAuth로, 아니면 API Key로 판별합니다. |
| scope | 읽기는 mcp:read, 쓰기는 mcp:write(읽기 포함)입니다. OAuth는 동의 화면에서 사용자가 승인한 scope를, API Key는 발급할 때 정한 scope 조합을 따릅니다. |
| 계정 role | 툴마다 필요한 계정 role이 선언되어 있고 정확히 일치해야 합니다. 사용자 툴 27종은 USER 전용, 관리자 툴 23종은 ADMIN 전용입니다. SUPER_ADMIN 계정은 어느 쪽도 호출할 수 없습니다 — role 하이어라키가 적용되지 않습니다. |
| tenant | 요청 host로 tenant를 판별합니다. 관리자 툴이 지정하는 userSeq·apiKeySeq는 같은 tenant 소속만 허용합니다. |
인증과 scope 조합, API Key 수명 주기는 Authentication에 있습니다. 같은 키로 Document Management API도 인증합니다.
전송
MCP Streamable HTTP는 JSON-RPC 2.0을 HTTP POST로 나르므로 curl로 직접 호출할 수 있습니다. 모든 요청은 /mcp에
대한 POST이며 헤더 3종을 보냅니다.
Authorization: Bearer replace-with-your-api-key— OAuth 액세스 토큰 또는 API Key입니다. 없으면 서버가401과WWW-Authenticate로 응답합니다.Content-Type: application/jsonAccept: application/json, text/event-stream— 두 미디어 타입 모두 필수입니다. 하나라도 빠지면400또는406입니다.
응답 본문은 application/json의 JSON-RPC 응답 그대로이며 SSE data: 프레임은 없습니다. GET /mcp는 405입니다.
MCP 클라이언트 라이브러리는 initialize와 notifications/initialized를 먼저 보내지만 curl에서는 둘 다 생략해도
됩니다. initialize를 보내면 200으로 응답하되 Mcp-Session-Id는 내려오지 않고 listChanged capability는 모두 false입니다.
툴 목록 조회
curl -X POST "https://drive.example.com/mcp" \
-H "Authorization: Bearer replace-with-your-api-key" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
result.tools[]에 툴 50종의 name, description, inputSchema가 담깁니다. 목록은 계정 role과 무관하게 전부
노출되고, 해당 계정이 쓸 수 없는 툴은 호출 시점에 거부됩니다.
툴 호출
tools/call의 결과에는 툴의 응답 봉투가 JSON 문자열로 직렬화되어 result.content[0].text에 담깁니다.
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{"type": "text", "text": "{\"data\":{}}"}
],
"isError": false
}
}
응답 봉투
모든 툴 결과는 봉투에 담깁니다. 성공은 {"data": {…}}이고, 예상된 실패 — 검증·권한·비즈니스 규칙 — 는
errorCode가 선택적으로 붙는 {"error": "…"}입니다.
성공 판정은 error 필드가 없는 것입니다. 예상된 실패는 인밴드로 전달됩니다. HTTP 상태는 그대로 200,
isError도 그대로 false이므로 전송 계층만 확인하는 클라이언트는 실패를 성공으로 읽게 됩니다.
값이 null인 필드는 직렬화된 data 객체에서 생략됩니다. 쓰기 툴 상당수는 성공해도 data 없이 빈 봉투 {}만
반환합니다. drive_admin_get_users_status 하나만 data가 객체가 아니라 배열입니다.
error의 메시지는 사람이 읽는 한국어 문자열이고, 분기 처리에 쓸 안정적인 값은 있을 때의 errorCode입니다. 코드
체계는 Document Management API와 같으며 Errors에 정리되어 있습니다.
{"error": "유저 정보를 찾을 수 없습니다.", "errorCode": "USER_005"}
툴 실행 전 검사
서버는 role → scope → tenant → 툴 본문 순으로 검사합니다.
| 검사 | 동작 |
|---|---|
| role | 계정 role이 툴에 선언된 role과 일치해야 합니다. 사용자 계정으로 관리자 툴을 부르면 거부되고 그 역방향도 같습니다. |
| scope | 쓰기 툴 30종(사용자 16 + 관리자 14)은 연결에 mcp:write가 없으면 거부됩니다. 읽기 툴은 둘 중 하나만 있으면 됩니다. |
| tenant | 관리자 툴이 지정한 userSeq·apiKeySeq는 요청 host의 tenant 소속이어야 합니다. 다른 tenant의 대상은 존재하지 않는 것처럼 USER_005 또는 API_KEY_001로 숨겨집니다. |
| 입력 | inputSchema의 required는 클라이언트 안내일 뿐 서버 강제가 아니라서, 각 툴이 자체 검증으로 누락을 인밴드 에러 "{parameter}는 필수입니다." 형태로 알립니다. |
툴이 인밴드로 검사하는 입력 규칙이 더 있습니다.
- 쌍으로만 의미가 있는 파라미터 — 날짜 범위의 시작과 끝,
cursorId와cursorValue,countryCode와phoneNumber— 는 함께 보내야 합니다. 빈 문자열은 미지정으로 취급합니다. - 길이 상한(
userName20자)과 미래 일시(expireDate)를 검사합니다. - SQL 예외는 원문을 노출하지 않고 입력값의 형식·길이를 확인하라는 일반 메시지로 되돌려 줍니다.
공통 규약
커서 페이지네이션. 목록 툴이 hasNext=true를 반환하면 nextCursor, nextCursorValue, nextCursorType을 다음
호출의 cursorId, cursorValue, cursorType으로 그대로 넘깁니다. 관리자 목록 툴은 대부분 단일 커서(nextCursor만
채워집니다)이고, drive_admin_list_pending_delete_users는 복합 커서입니다. drive_list_resource_versions만
예외적으로 오프셋 방식이라 totalCount 기준으로 pageIndex를 넘깁니다.
공유받은 리소스 접근. 다른 사용자가 공유해 준 리소스는 목록 항목의 sharedByUserSeq(없으면 userSeq)를 툴의
sharedByUserSeq로, 파라미터가 목적지를 가리키는 경우(복사·이동·생성)는 targetUserSeq로 넘깁니다. ownerSeq가
아닙니다. 내 리소스면 생략합니다.
웹 링크. 목록·조회·파일 툴은 브라우저에서 파일을 미리 보거나 폴더를 여는 링크인 webViewUrl을 반환합니다.
웹오피스에서 편집할 수 있는 형식이고 호출자에게 canEdit이 있으면 editUrl도 함께 옵니다.
날짜. startDate·endDate 같은 요청 날짜 범위는 yyyy-MM-dd이고 해당 일을 포함하며 양쪽 모두 지정해야
합니다. expireDate는 yyyy-MM-ddTHH:mm:ss 또는 yyyy-MM-dd이고 후자는 그 날 23:59:59로 해석됩니다. 응답의
일시 필드는 yyyy-MM-dd HH:mm:ss 형태의 문자열이며 날짜 커서 값에는 .SSS가 붙습니다.
권한과 감사. 각 툴은 대응하는 웹 API와 같은 권한 검사와 usecase를 사용하고, 감사 로그와 사용자 로그도 웹 제품과 동일하게 남깁니다. 관리자 툴에 보낸 비밀번호는 서버 로그에 기록하지 않습니다.
사용자 툴
USER 계정으로만 호출할 수 있는 27종입니다.
| 분류 | 툴 | scope | 용도 |
|---|---|---|---|
| 검색 | drive_search_resources | READ | 이름 검색 또는 폴더 내용 조회, 기본 범위는 내 드라이브 |
| 검색 | drive_get_resource_metadata | READ | 리소스 1건의 상세 메타데이터와 요청자 권한 6종 |
| 문서함 | drive_list_recent_resources | READ | 최근 열람·수정한 리소스, 공유받은 것 포함 |
| 문서함 | drive_list_starred_resources | READ | 중요 문서로 등록한 리소스 |
| 문서함 | drive_list_trash_resources | READ | 삭제된 리소스, 삭제자와 삭제일 포함 |
| 문서함 | drive_list_shared_resources | READ | 나에게 공유된 리소스 |
| 파일 | drive_read_file | READ | 본문을 텍스트로 반환 — 평문 21종, 추출 15종(10MB, 5만 자) |
| 파일 | drive_download_file | READ | 원본 바이트를 base64로 반환, 전 형식(10MB) |
| 파일 | drive_upload_file | WRITE | 텍스트나 base64 내용으로 새 파일 업로드(512KB) |
| 파일 | drive_create_file | WRITE | 빈 오피스 문서 생성(word, excel, ppt, note) |
| 파일 | drive_copy_file | WRITE | 파일 1건 복제, 폴더는 미지원 |
| 폴더 | drive_create_folder | WRITE | 폴더 생성, 동명이면 자동 번호 |
| 변경 | drive_move_resource | WRITE | 파일·폴더 이동, 폴더는 하위 전체 포함 |
| 변경 | drive_rename_resource | WRITE | 파일·폴더 이름 변경 |
| 중요 문서 | drive_star_resource | WRITE | 중요 문서로 등록 |
| 중요 문서 | drive_unstar_resource | WRITE | 중요 문서 해제, starredSeq 기준 |
| 휴지통 | drive_delete_resource | WRITE | 휴지통으로 이동, 복원 가능 |
| 휴지통 | drive_restore_trash_resource | WRITE | 휴지통에서 원위치로 복원 |
| 휴지통 | drive_delete_trash_resource_permanently | WRITE | 영구 삭제하고 쿼터 반환, 복구 불가 |
| 버전 | drive_list_resource_versions | READ | 파일의 버전 이력 |
| 버전 | drive_restore_resource_version | WRITE | 이전 버전으로 되돌리기 |
| 버전 | drive_delete_resource_version | WRITE | 특정 버전 영구 삭제, 소유자 전용 |
| 공유 | drive_get_share_permissions | READ | share type, 기본 권한, 대상 명단 조회 |
| 공유 | drive_search_share_users | READ | 이름·이메일로 공유 대상 후보 검색 |
| 공유 | drive_share_resource | WRITE | share type·기본 권한·대상의 소유자 전용 upsert |
| 공유 | drive_update_share_targets | WRITE | canShare 위임자가 대상 명단 교체 |
| 공유 | drive_unshare_resource | WRITE | 공유 완전 해제, 소유자 전용이며 복구 불가 |
관리자 툴
ADMIN 계정으로만 호출할 수 있는 23종이며, 이름에 모두 drive_admin_ 접두가 붙습니다.
| 분류 | 툴 | scope | 용도 |
|---|---|---|---|
| 계정 조회 | drive_admin_list_admins | READ | ADMIN 계정 목록, status 필터, userSeq 커서 |
| 계정 조회 | drive_admin_list_users | READ | USER 계정 목록, status·사용자 ID 필터, userSeq 커서 |
| 계정 조회 | drive_admin_search_users | READ | 이름·이메일 부분 일치, 활성 USER만이고 커서 없음 |
| 계정 조회 | drive_admin_get_user | READ | 용량·전화·MFA 포함 상세, 삭제 상태 계정도 조회 |
| 계정 조회 | drive_admin_get_users_status | READ | 이메일을 넣으면 userSeq와 status 반환, data가 배열 |
| 계정 조회 | drive_admin_get_user_storage_usage | READ | 할당·총·파일·버전·휴지통 byte |
| 계정 조회 | drive_admin_list_user_logs | READ | LOGIN·LOGOUT·CHANGE_PASSWORD 로그, userLogSeq 커서 |
| 계정 관리 | drive_admin_register_user | WRITE | 계정 단건 등록, 외부 인증 계정은 ADMIN 불가 |
| 계정 관리 | drive_admin_update_user | WRITE | 부분 수정, 생략한 필드는 유지 |
| 계정 관리 | drive_admin_update_user_password | WRITE | 비밀번호 변경과 로그인 실패 횟수 초기화 |
| 계정 관리 | drive_admin_activate_user | WRITE | INACTIVE에서 ACTIVE로 |
| 계정 관리 | drive_admin_deactivate_user | WRITE | ACTIVE에서 INACTIVE로, 본인과 기본 관리자는 불가 |
| 계정 관리 | drive_admin_bulk_upsert_users | WRITE | 배열 upsert를 단일 트랜잭션으로, 수정은 전체 교체 |
| 삭제 | drive_admin_withdraw_user | WRITE | PENDING_DELETE로 전환, 약 30일 후 완전 삭제 |
| 삭제 | drive_admin_list_pending_delete_users | READ | 삭제 대기 계정, 날짜 범위 필터, 복합 커서 |
| 삭제 | drive_admin_restore_user | WRITE | PENDING_DELETE에서 INACTIVE로 |
| 삭제 | drive_admin_delete_user | WRITE | cascade 삭제 후 DELETED, 복구 불가 |
| API Key | drive_admin_list_api_keys | READ | tenant의 키 목록, 마스킹, apiKeySeq 커서 |
| API Key | drive_admin_create_api_key | WRITE | 본인 또는 USER 대상 발급, 원문은 1회만 노출 |
| API Key | drive_admin_reissue_api_key | WRITE | 키 원문 교체와 ACTIVE 복귀, 만료일은 그대로 |
| API Key | drive_admin_activate_api_key | WRITE | INACTIVE에서 ACTIVE로, 멱등 |
| API Key | drive_admin_deactivate_api_key | WRITE | ACTIVE에서 INACTIVE로, 멱등이며 자기 키도 끌 수 있음 |
| API Key | drive_admin_update_api_key_expire_date | WRITE | 미래 일시만 지정 가능, 만료된 키의 복구 경로 |
drive_delete_trash_resource_permanently, drive_delete_resource_version, drive_unshare_resource,
drive_admin_delete_user는 되돌릴 수 없습니다. 연결된 계정이 그런 변경까지 수행해야 하는 경우에만 AI 클라이언트에
mcp:write를 부여합니다.