MCP
Thinkfree Drive는 /mcp 경로에서 MCP(Model Context Protocol) 서버를 제공합니다. Claude 앱, Claude Code 등의 MCP
클라이언트를 OAuth 2.0 또는 API Key로 연결하면 AI 클라이언트가 연결된 계정의 권한으로 Drive 기능을 호출합니다.
일반 사용자(USER) 계정은 파일·폴더·공유 툴을, 관리자(ADMIN) 계정은 계정·API Key 툴을 사용할 수 있습니다.
서버는 사용자 툴 27개와 관리자 툴 23개, 모두 50개의 툴을 제공합니다.
| 항목 | 내용 |
|---|---|
| endpoint | tenant 서브도메인의 /mcp, Streamable HTTP. Stateless 방식이므로 Mcp-Session-Id 세션을 사용하지 않으며, initialize 없이 tools/list·tools/call을 개별 요청으로 호출합니다. |
| 인증 | Authorization: Bearer replace-with-your-api-key 헤더에 OAuth 2.0 access token(동적 클라이언트 등록과 사용자 동의로 발급) 또는 API Key(관리자 화면에서 발급하는 문자열)를 담습니다. 서버는 값이 JWT 형식이면 OAuth access token으로, 그렇지 않으면 API Key로 판단합니다. |
| scope | 읽기에는 mcp:read, 쓰기에는 mcp:write(읽기 포함)가 필요합니다. OAuth는 사용자가 동의 화면에서 승인한 scope를, API Key는 발급할 때 지정한 scope 조합을 사용합니다. |
| 계정 role | 툴마다 필요한 계정 role이 정해져 있으며, 계정의 role과 정확히 일치해야 합니다. 사용자 툴 27개는 USER 전용, 관리자 툴 23개는 ADMIN 전용입니다. role 간 상하 관계가 적용되지 않으므로 SUPER_ADMIN 계정은 두 종류의 툴 모두 호출할 수 없습니다. |
| 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이며 다음 세 가지 헤더를 보냅니다.
Authorization: Bearer replace-with-your-api-key- OAuth access token 또는 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": {…}}를 반환하고, 입력 검증·권한·업무 규칙
위반처럼 예상된 실패는 {"error": "…"}로 반환하며 errorCode가 포함될 수 있습니다.
error 필드가 없으면 성공입니다. 예상된 실패도 정상 응답 안에 담겨 전달됩니다. HTTP 상태는 200, isError는
false로 반환되므로 HTTP 상태나 isError만 확인하는 클라이언트는 실패를 성공으로 처리할 수 있습니다.
값이 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가 없으면 거부됩니다. 읽기 툴은 두 scope 중 하나만 있으면 호출할 수 있습니다. |
| tenant | 관리자 툴에 지정한 userSeq·apiKeySeq는 요청한 host의 tenant에 속해야 합니다. 다른 tenant의 대상을 지정하면 존재하지 않는 대상과 마찬가지로 USER_005 또는 API_KEY_001을 반환합니다. |
| 입력 | inputSchema의 required는 클라이언트에 대한 안내이며 서버에서 강제하지 않습니다. 각 툴이 직접 입력을 검증하며, 필수 값이 없으면 "{parameter}는 필수입니다." 형식의 오류를 응답 객체로 반환합니다. |
각 툴은 다음 입력 규칙도 검사합니다.
- 날짜 범위의 시작과 끝,
cursorId와cursorValue,countryCode와phoneNumber처럼 함께 사용해야 하는 파라미터는 반드시 함께 보내야 합니다. 빈 문자열은 값을 지정하지 않은 것으로 처리합니다. - 최대 길이(
userName20자)와 현재 이후의 일시(expireDate)인지 검사합니다. - 데이터베이스 오류가 발생하면 상세 내용을 표시하지 않고, 입력값의 형식과 길이를 확인하라는 일반 메시지를 반환합니다.
공통 규약
cursor 페이지네이션. 목록 툴이 hasNext=true를 반환하면 nextCursor, nextCursorValue, nextCursorType을 다음
호출의 cursorId, cursorValue, cursorType으로 그대로 보냅니다. 관리자 목록 툴은 대부분 단일 cursor를 사용하며
nextCursor만 반환합니다. drive_admin_list_pending_delete_users는 여러 값으로 구성된 cursor를 사용합니다.
drive_list_resource_versions만 offset 방식이므로 totalCount를 기준으로 pageIndex를 지정합니다.
공유받은 리소스. 다른 사용자가 공유한 리소스를 다룰 때는 목록 항목의 sharedByUserSeq(없으면 userSeq)를 툴의
sharedByUserSeq로 보냅니다. 복사·이동·생성처럼 대상 위치를 지정하는 경우에는 targetUserSeq로 보냅니다. 이때
ownerSeq를 사용하지 않습니다. 본인의 리소스면 생략합니다.
웹 링크. 목록·조회·파일 툴은 브라우저에서 파일을 미리 보거나 폴더를 여는 webViewUrl을 반환합니다. Office에서
편집할 수 있는 형식이고 호출한 계정에 canEdit 권한이 있으면 editUrl도 함께 반환합니다.
날짜. startDate·endDate 같은 요청 날짜 범위는 yyyy-MM-dd 형식이며, 지정한 날짜를 포함하고 두 값을 모두
지정해야 합니다. expireDate는 yyyy-MM-ddTHH:mm:ss 또는 yyyy-MM-dd 형식이며, yyyy-MM-dd로 지정하면 해당
날짜의 23:59:59로 처리합니다. 응답의 일시 필드는 yyyy-MM-dd HH:mm:ss 형식의 문자열이며, 날짜 cursor 값에는
.SSS가 붙습니다.
권한과 감사 로그. 각 툴은 대응하는 웹 API와 같은 권한 검사와 처리 로직을 사용하며, 감사 로그와 사용자 로그도 웹 화면에서 작업할 때와 같이 기록합니다. 관리자 툴로 보낸 비밀번호는 서버 로그에 기록하지 않습니다.
사용자 툴
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 | 빈 Office 문서 생성(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 | 공유 유형, 기본 권한, 공유 대상 목록 조회 |
| 공유 | drive_search_share_users | READ | 이름·이메일로 공유할 사용자 검색 |
| 공유 | drive_share_resource | WRITE | 공유 유형·기본 권한·공유 대상을 생성하거나 수정, 소유자 전용 |
| 공유 | drive_update_share_targets | WRITE | canShare 권한을 받은 사용자가 공유 대상 목록을 교체 |
| 공유 | drive_unshare_resource | WRITE | 공유를 완전히 해제, 소유자 전용이며 복구 불가 |
관리자 툴
ADMIN 계정으로만 호출할 수 있는 툴 23개이며, 이름이 모두 drive_admin_으로 시작합니다.
| 분류 | 툴 | scope | 용도 |
|---|---|---|---|
| 계정 조회 | drive_admin_list_admins | READ | ADMIN 계정 목록, status 필터, userSeq cursor |
| 계정 조회 | drive_admin_list_users | READ | USER 계정 목록, status·사용자 ID 필터, userSeq cursor |
| 계정 조회 | drive_admin_search_users | READ | 이름·이메일 부분 일치 검색, 활성 USER 계정만 조회, cursor 없음 |
| 계정 조회 | 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 cursor |
| 계정 관리 | drive_admin_register_user | WRITE | 계정 1건 등록, 외부 인증 계정으로는 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 | 여러 계정을 하나의 트랜잭션으로 등록·수정, 수정할 때는 전체 필드를 교체 |
| 삭제 | drive_admin_withdraw_user | WRITE | PENDING_DELETE로 전환, 약 30일 후 완전 삭제 |
| 삭제 | drive_admin_list_pending_delete_users | READ | 삭제 대기 계정, 날짜 범위 필터, 여러 값으로 구성된 cursor |
| 삭제 | drive_admin_restore_user | WRITE | PENDING_DELETE에서 INACTIVE로 변경 |
| 삭제 | drive_admin_delete_user | WRITE | 관련 데이터를 함께 삭제한 뒤 DELETED로 변경, 복구 불가 |
| API Key | drive_admin_list_api_keys | READ | tenant의 키 목록, 키 값은 마스킹, apiKeySeq cursor |
| API Key | drive_admin_create_api_key | WRITE | 본인 또는 USER 계정에 키 발급, 전체 키 값은 한 번만 표시 |
| 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를 부여하세요.