AI Drive MCP 서버
Claude Desktop 같은 외부 MCP 클라이언트에서 Keural 드라이브 문서를 검색하고 읽습니다.
Keural 드라이브를 MCP 서버로 제공합니다. 외부 MCP 클라이언트를 연결하면 키를 발급받은 사용자가 볼 수 있는 드라이브 문서를 검색하고 페이지 단위로 읽습니다. 플러그인은 외부 시스템을 Keural에 연결하고, 이 서버는 Keural 문서를 외부 AI에 연결합니다.
인증에는 조직 API 키를 씁니다. 조직 API 키는 Keural 운영 측이 발급하므로 도입 담당자에게 요청합니다. 키는 발급받은 사용자 한 명의 권한으로 동작하며 drive:read 권한이 필요합니다. 키를 회수하면 1분 안에 기존 연결도 차단됩니다.
연결 정보
| 항목 | 값 |
|---|---|
| 전송 방식 | MCP Streamable HTTP |
| 주소 | https://<환경별 에이전트 서버 도메인>/core/v1/mcp-drive |
| 인증 | Authorization: Bearer <조직 API 키> (모든 요청) |
요청 방식
| 메서드 | 쓰임 |
|---|---|
POST | JSON-RPC 요청 한 건. 응답은 항상 application/json 하나입니다. 알림(notifications/*)은 본문 없이 202를 반환합니다. |
GET | 서버 이벤트 스트림. Accept: text/event-stream과 Mcp-Session-Id가 필요합니다. 15초마다 keepalive를 보내고 Last-Event-ID로 이어 받습니다. |
DELETE | 세션 종료. Mcp-Session-Id가 필요하며 204를 반환합니다. |
initialize에 성공하면 응답 헤더Mcp-Session-Id로 세션 ID를 반환합니다. 세션은 선택이며, 세션 없이POST만 보내도 됩니다. 세션은 마지막 요청 후 1시간 동안 유지되며 만든 키에 묶입니다.MCP-Protocol-Version헤더는 선택이며, 보내면2025-06-18이어야 합니다.- 서버 정보는
keural-ai-drive이고, 제공 기능은tools뿐입니다.
HTTP 오류
HTTP 단계 오류는 JSON-RPC 형식이 아니므로 상태 코드로 확인합니다.
| 상태 | 원인 |
|---|---|
401 | 키가 없거나 틀림, 회수·만료된 키 |
403 | 키에 drive:read 권한이 없음 |
400 | 지원하지 않는 MCP-Protocol-Version, JSON 파싱 실패(-32700), GET·DELETE에 세션 ID가 없음 |
404 | 알 수 없거나 만료된 세션 ID |
405 | GET에 Accept: text/event-stream이 없음 |
JSON-RPC 단계 오류는 200과 함께 error로 반환합니다. 알 수 없는 메서드·도구는 -32601, 잘못된 요청 형식은 -32600입니다.
도구
| 도구 | 입력 | 설명 |
|---|---|---|
list_files | 없음 | 볼 수 있는 문서 목록(이름, id, 올린 날짜, 수정 날짜, 다른 사람이 올린 경우 올린 사람). 드라이브 문서와 채팅 첨부 파일이 함께 반환되며 origin으로 구분합니다. 최대 500개이며, 넘으면 truncated: true가 붙습니다 |
search_drive | query | 문서 내용을 의미 검색해 관련 구절과 인용 정보를 반환합니다 |
read_document_page | file_id, page | 문서의 특정 페이지 전문을 읽습니다. file_id는 위 두 도구의 결과에서 가져오고, page는 1부터 셉니다 |
도구 결과는 content[0].text에 JSON 문자열로 담깁니다.
| 도구 | text 안의 JSON |
|---|---|
list_files | {"files":[{"name","id","created_date","modified_date","owner_name","origin"}], "truncated": false}. 날짜는 yyyy-MM-dd HH:mm |
search_drive | {"sources":[{"id","name","url","contents":[…]}]} |
read_document_page | {"file_id","page","rows":[…]} |
도구 실행이 실패하면 isError: true와 {"error": "…"}를 반환합니다(JSON-RPC 오류 아님). 권한이 없거나 존재하지 않는 문서는 모두 file not found or not accessible을 반환합니다.
클라이언트 설정 예
원격 MCP 서버를 지원하는 클라이언트에 주소와 헤더를 등록합니다. 설정 형식은 클라이언트마다 다르므로 해당 클라이언트의 원격 MCP 서버 추가 방법을 따릅니다.
{
"mcpServers": {
"keural-drive": {
"type": "http",
"url": "https://<환경별 에이전트 서버 도메인>/core/v1/mcp-drive",
"headers": { "Authorization": "Bearer <조직 API 키>" }
}
}
}MCP 프로토콜 버전은 2025-06-18을 지원합니다.