공식 MCP 서버(v1.9.1)는 **27개 툴 (tools)**을 공개. 앱 생성 → 필드 정의 → 배포 → 레코드 CRUD까지 전부 AI로부터 조작할 수 있다. 완성도는 높다 - 다만

(1) 생성 직후의 앱에 레코드를 추가하면 "앱을 찾을 수 없습니다. 삭제되었을 가능성이 있습니다"라는 거짓 404 에러가 발생한다 (실제로는 미배포 상태일 뿐임) -
(2) 유효성 검사 에러(Validation error)는 "입력 내용이 올바르지 않습니다"라고만 표시되어, REST API가 본래 반환하는 필드별 상세 정보가 MCP 계층에서 사라진다. AI는 무엇을 수정해야 할지 알 수 없다 -
(3) 필드 설정을 변경해도 배포 상황 툴은 SUCCESS를 계속 반환한다. "필수로 설정했다"고 생각한 변경 사항이 운영 환경에 반영되지 않은 채, 위반 레코드가 그대로 통과된다 (실측) -
(4)(5) 모든 툴에 위험도 메타데이터(annotations)가 없고, 읽기 전용(Read-only) 모드도 없다. 권한은 부여된 계정 그대로 유지된다. 도메인을 넘나드는 전체 검색 툴까지 존재한다 - 결론: 서버는 나쁘지 않다. "전부 통과되어 버린다"는 점이 위험하다. AI에게 kintone을 맡기는 시대의 권한 설계와 검증은 아직 거의 공백 영역이다

Cybozu가 2025년 8월에 공식 로컬 MCP 서버를 공개하여, Claude Desktop 등의 AI 툴로부터 kintone을 직접 조작할 수 있게 되었다 (릴리스 공지, GitHub).

"AI가 업무용 앱을 만들어 준다"는 체험은 강력하지만, 실무에서 사용하려면 AI로부터 보이는 세계가 어떻게 되어 있는지를 먼저 알고 있어야 한다. 이에 본 기사에서는 AI 클라이언트를 거치지 않고, MCP 프로토콜 (stdio 상의 JSON-RPC)을 직접 호출하여 "AI에게 앱을 만들게 하는" 조작 시퀀스를 그대로 재현하고 거동을 관찰했다. AI의 응답이라는 불확정 요소를 끼워 넣지 않으므로, 서버 측의 순수한 거동을 알 수 있다.

@kintone/mcp-server

v1.9.1 (npm・Apache-2.0) - Node.js 22 / macOS

• kintone
  개발자 라이선스 환경・패스워드 인증 - 참고로 kintone AI (앱 생성 AI 등・2026년 6월 정식 버전)는 개발자 라이선스에서는 제공되지 않으며, 이번 검증 대상에서 제외되었다 (포털・앱 생성・검색 중 어느 곳에서도 AI 계열 UI가 나타나지 않음을 실기 확인). 본 기사는 "외부 AI × 공식 MCP 서버"에 초점을 맞춘다.

셋업은 3분이면 끝난다.

npm install @kintone/mcp-server
KINTONE_BASE_URL=https://example.cybozu.com \
KINTONE_USERNAME=xxx \
...

MCP의 stdio 트랜스포트(transport)는 개행으로 구분된 JSON-RPC이므로, 자식 프로세스에 한 줄씩 JSON을 쓰기만 하면 대화할 수 있다.

// initialize → tools/list → tools/call 을 순차적으로 던지는 최소 클라이언트 (발췌)
server.stdin.write(JSON.stringify({
jsonrpc: "2.0", id: 1, method: "initialize",
...

tools/list 결과의 분류는 다음과 같다.

앱 생성부터 필드 정의, 배포(deploy), 레코드 CRUD, 스페이스 삭제까지 전반적인 기능이 갖춰져 있습니다. 반대로 없는 것도 중요합니다. 목록(뷰) 설정・접근 권한・알림・프로세스 관리 변경・플러그인 설정・JS/CSS 커스터마이징・앱 삭제는 수행할 수 없습니다 (애초에 앱을 삭제하는 REST API가 존재하지 않습니다).

참고로 README의 툴 목록표는 26개이며, kintone-search는 표에 포함되어 있지 않습니다 (v1.9.1 기준). 즉, 툴의 기능적 범위(tool surface area)는 계속해서 늘어나고 있다는 의미입니다.

AI 클라이언트가 수행할 법한 작업 순서를 그대로 실행해 보았습니다.

kintone-add-app

(앱 이름: 프로젝트 관리) → 즉시 {"app":"398"}이 반환됨 -
kintone-add-form-fields

(회사명=필수 텍스트・금액=숫자・상태=드롭다운・기한=날짜) -
kintone-deploy-app

→ kintone-get-app-deploy-status로 SUCCESS 대기 -
kintone-add-records

으로 레코드 입력 -
kintone-get-records

으로 확인

모두 정상적으로 작동합니다. 앱 생성부터 레코드 입력까지 1분 남짓입니다. 이 경험 자체는 훌륭합니다.

문제는, 이 과정 전후에서 발견한 다음 5가지 사항입니다.

절차 1 직후(배포 전)에 레코드를 추가하려고 하면 다음과 같이 됩니다.

[404] [GAIA_AP01] 지정된 앱(id: 398)을 찾을 수 없습니다. 삭제되었을 가능성이 있습니다.

실제로는 삭제되지 않았습니다. kintone-add-app은 작동 테스트 환경에 앱을 만들기 때문에, kintone-deploy-app으로 운영 환경에 반영될 때까지 레코드 API에서는 보이지 않는 것이 정확한 설명입니다.

사람이라면 도움말을 찾아내고 알아차릴 수 있지만, AI는 이 오류 문구를 문자 그대로 받아들입니다.

AI 클라이언트에게 이 차이는 치명적입니다. 상세 정보가 있다면 한 번에 스스로 수정할 수 있는 것이, "무언가 잘못되었다"라고밖에 알 수 없기 때문에 짐작으로 리트라이(Retry)를 반복하게 됩니다 (토큰과 시간도 낭비됩니다).

한 번 배포한 후, kintone-update-form-fields로 금액 필드를 required: true로 변경했습니다. 이 상태에서 kintone-get-app-deploy-status를 호출하면——

{"apps":[{"app":"398","status":"SUCCESS"}]}

SUCCESS입니다. 이 도구가 반환하는 것은 "마지막 배포 작업의 결과"이지, "미반영된 변경 사항이 있는지"가 아닙니다. UI에서 설정 화면을 열면 "반영 전 변경 사항이 있습니다"라는 배너가 명확하게 떠 있는데, MCP를 통한 풍경에서는 보이지 않습니다.

실측을 통해 확인된 결과: 이 상태에서 금액이 없는 레코드를 투입하면, 정상적으로 성공합니다. 운영 환경은 구형 정의(금액=선택 사항) 상태로 동작하고 있기 때문입니다. AI는 "필수화했다"라고 보고하고, 인간은 그것을 믿으며, 운영 환경에서는 위반 데이터가 계속 쌓여가는——식의 시나리오가 실제로 일어날 수 있습니다.

대책: 변경 계열 작업 후에는 반드시 deploy-app을 실행할 것. 더 엄밀하게는 get-form-fields를 preview: true와 false로 모두 호출하여 차이(diff)를 구하면 미반영 변경 사항을 검출할 수 있습니다 (preview 파라미터는 존재하지만, AI가 자발적으로 diff를 취할 것이라고 기대할 수 없으므로 절차서에서 강제해야 합니다).

MCP에는 도구에 readOnlyHint나 destructiveHint 같은 어노테이션(Annotation)을 붙여 클라이언트에게 위험도를 전달하는 메커니즘이 있습니다. v1.9.1의 27개 도구는 모두 어노테이션이 없었습니다.

즉 클라이언트 입장에서 보면, kintone-get-app(읽기 전용)과 kintone-delete-space(스페이스 삭제)가 동등한 등급입니다. 읽기 전용 모드도, 사용하는 도구를 제한하는 설정도 없습니다. AI 클라이언트 측의 확인 다이얼로그 설정만이 마지막 보루가 됩니다.

패스워드 인증으로 관리자 계정을 넘겨주면, AI는 해당 사용자가 볼 수 있는 모든 것을 읽고 쓸 수 있습니다. 게다가 kintone-search는 도메인 횡단 전체 검색(레코드·스페이스·댓글·첨부 파일)이므로, "경리 앱의 급여 데이터를 실수로 문맥에 포함하는" 일도 기술적으로 충분히 일어날 수 있습니다.

API 토큰 인증(쉼표로 구분하여 최대 9개)을 사용하면 대상 앱과 권한을 제한할 수 있습니다. 실측 결과, 토큰 인증으로 기동하면 도구 목록 자체가 27개에서 20개로 줄어들며, kintone-add-app · kintone-get-apps · kintone-search · 스페이스 관련 4종은 처음부터 나타나지 않습니다 (tools/list에 존재하지 않음). 토큰 대상 외의 앱에 대한 액세스도 [403] GAIA_AP15로 명확하게 거부됩니다. 이 부분은 설계가 잘 되어 있습니다. 다만 뒤집어 말하면, "앱을 만들게 하고 싶다"면 사용자 인증으로 넘겨줄 수밖에 없다는 구조는 변하지 않습니다.

검증을 바탕으로 한 현시점의 자위책입니다.

• AI 전용 사용자를 만든다. 관리자 계정을 넘겨주지 않는다. 감사 로그(Audit Log)도 사용자 단위이므로, AI의 조작을 인간의 조작과 구분할 수 있게 된다.
• 용도에 따라 서버 설정을 분리한다. 레코드 조작만 한다면 API 토큰 인증을 사용한다——서버 자체가 앱 생성·횡단 검색·스페이스 관련 도구를 제외해 주기 때문에(실측 27개 $\rightarrow$ 20개) 이것이 실질적인 읽기/쓰기 범위의 제한이 된다. 앱 구축을 시키고 싶을 때만 저권한 사용자의 패스워드 인증을 사용한다.
• 운영 도메인에서 바로 사용하지 않는다. 개발자 라이선스 환경(무료)에서 동작을 파악한 뒤에 사용한다.
• AI의 "완료했습니다"를 신뢰하지 말고 검증한다. 배포 상태·preview/운영의 차이·필수/타입 충족 여부는 위에서 본 바와 같이 "성공한 것처럼 보이지만 반영되지 않은" 패턴이 있으므로, 사람이나 스크립트로 재확인한다.
• 절차서에 함정 1~3에 대한 대처법을 명시한다. 에러 문구를 AI가 오독할 것을 전제로 작성한다.

공식 MCP 서버 자체는 잘 만들어져 있습니다. 1분 만에 앱이 구축되고 레코드가 들어갑니다. 비판하고 싶은 것이 아니라, 오히려 전부 통과되기 때문에 권한·검증·감사 설계를 사용하는 측에서 직접 챙겨야 한다는 것이 이번의 결론입니다.

도구의 표면적(Tool surface area)은 앞으로도 계속 늘어날 것입니다 (README 표에 기재되지 않은 kintone-search가 이미 존재하는 것처럼 말이죠). "AI가 kintone을 조작하는 것"이 당연해졌을 때, AI가 만든 것을 누가 어떻게 검증할 것인가와 AI에게 무엇을 어디까지 허용할 것인가는 아직 아무도 답을 가지고 있지 않은 공백 지대입니다. 이 부분은 계속해서 추적하며 알아낸 내용을 기록해 나가겠습니다.

검증은 2026년 7월·v1.9.1 시점의 것입니다. kintone 로컬 MCP 서버는 API 지원 창구의 대상이 아니며, 사양은 향후 변경될 가능성이 있습니다. 버그 보고 및 기능 요청은 GitHub Issues를 이용해 주세요.

평소에는 kintone용 플러그인을 Plumeru에서 개발 및 배포하고 있습니다.