인사책 AI 비서 연동 시작하기
이 문서는 인사책 MCP 서버를 처음 여는 사람을 위한 것입니다.
토큰을 받아 첫 요청을 보내고,
응답이 이상할 때 오류 코드로 원인을 짚는 데까지를 순서대로 적었습니다.
인증 전 공개 카탈로그에는 조회 도구 108개가 실리고,
연결한 뒤에는 전체 도구 214개(조회 108개 · 변경 106개)를 각자의 권한 안에서 씁니다.
도구가 무엇을 할 수 있는지,
어떤 권한이 필요한지는 MCP 연동 문서가 갖고 있습니다.
이 면은 그 앞 단계인 연결과 규격만 다룹니다.
AI 비서 연동 인증 — OAuth 와 PAT 중 하나
둘 다 요청 헤더에 Authorization: Bearer 로 붙는 문자열 하나를 얻는 절차이고,
그 문자열이 회사·역할·scope 를 이미 담고 있습니다.
붙이는 방법은 같습니다.
다른 것은 수명 하나입니다.
OAuth 액세스 토큰은 30일 뒤 만료되고,
함께 받은 리프레시 토큰(90일)으로 새로 받습니다 — 갱신하면 액세스 토큰과 리프레시 토큰이 둘 다 새것으로 바뀌므로 옛 리프레시 토큰은 버리세요.
PAT 은 만료일이 없어 폐기할 때까지 그대로 씁니다.
원클릭 OAuth — Claude.ai · ChatGPT 권장
커넥터/MCP 추가 화면에 아래 서버 주소만 붙여넣고 Connect 를 누르면 브라우저에 로그인·승인 창이 자동으로 열립니다.
토큰을 손으로 복사할 일이 없습니다.
- 커넥터 추가 → URL 칸에 위 주소 → Connect
- 자동으로 열리는 창에서 로그인 (개인 · 근로자 · 기업 관리자 모두 됩니다)
- 승인 → 끝.
기업 관리자로 로그인하면 부서 · 직원 · 대표/팀장 지정 · 근로계약서까지 회사 전체를 AI 로 설정할 수 있습니다.
창이 안 열리거나 구버전 클라이언트라면 아래 PAT 를 쓰세요.
PAT 토큰 — Claude Desktop · Cursor · CLI
- 로그인한 뒤 /worker/mcp 에서 개인 액세스 토큰을 발급합니다.
- 클라이언트의 MCP 설정에 서버 URL 과 그 토큰을 함께 넣습니다.
- 「무슨 기능 있어?」라고 물으면 내 권한으로 가능한 것을 스스로 안내합니다.
첫 호출 — initialize 로 악수한 뒤 tools/list
첫 요청인 initialize 는 토큰 없이도 성공합니다.
여기서 실패시키면 커넥터가 「연결 오류」만 보여 주고 사람이 이유를 못 보기 때문입니다.
POST https://insacheck.com/api/mcp
Content-Type: application/json
MCP-Protocol-Version: 2025-06-18
{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": { "protocolVersion": "2025-06-18" } }
보낸 protocolVersion 이 지원 목록에 있으면 그대로 되돌려주고,
없거나 안 보냈으면 최신값으로 맞춰서 답합니다.
그다음 같은 주소로 토큰을 붙여 tools/list 를 부르면 내 권한 안의 것만 추려서 돌아옵니다.
POST https://insacheck.com/api/mcp
Authorization: Bearer <PAT 또는 OAuth access token>
Content-Type: application/json
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }
요청 형태와 지원 메서드
전송 방식은 하나입니다 — https://insacheck.com/api/mcp 로 보내는 JSON-RPC 2.0 POST.
메서드마다 인증 필요 여부가 다릅니다.
| method | 인증 | 응답 |
|---|---|---|
| initialize | 필요 없음 | 핸드셰이크. protocolVersion·capabilities·serverInfo 와 서버 지침이 돌아옵니다. |
| ping | 필요 없음 | 빈 결과만 돌아옵니다. 연결이 살아 있는지 볼 때 씁니다. |
| notifications/* | 필요 없음 | HTTP 202 로 받기만 하고 본문을 만들지 않습니다(단방향 통지). |
| tools/list | 필요 | 내 역할과 scope 로 실행할 수 있는 것만 추려서 돌아옵니다. |
| tools/call | 필요 | content 배열과 isError 를 담은 결과가 돌아옵니다. |
| 그 밖의 메서드 | 필요 | 토큰 없이 부르면 -32001 이 먼저 오고, 인증을 통과한 뒤에 -32601 로 거절합니다. resources/* · prompts/* 는 아직 구현하지 않았습니다. |
오류 코드
JSON-RPC 규약대로 코드가 붙습니다.
HTTP 상태와 코드가 따로 움직인다는 점만 주의하세요 — 거절 대부분은 HTTP 200 안에 코드로 담겨 옵니다.
| code | HTTP | 언제 오나 |
|---|---|---|
| -32700 | 400 | 본문이 JSON 으로 파싱되지 않았습니다. |
| -32600 | 400 | jsonrpc 나 method 가 빠졌거나, MCP-Protocol-Version 헤더가 지원 밖 값입니다. 지원 값은 2025-06-18 · 2025-03-26 · 2024-11-05 입니다. |
| -32601 | 200 | 지원하지 않는 메서드입니다. |
| -32001 | 401 또는 200 | 토큰이 없거나 만료됐거나, 그 도구를 쓸 권한이 아닙니다. 401 로 올 때는 재로그인 안내 헤더가 함께 옵니다. |
| -32003 | 200 | 그 토큰의 하루 호출 한도를 넘었습니다. |
| -32004 | 200 | 두 가지입니다. 위험 작업 확인 토큰이 만료·재사용됐거나 발급되지 않았을 때, 그리고 회사 단위 한 달 호출 한도를 다 썼을 때입니다. 메시지 본문으로 어느 쪽인지 가릅니다. |
호출 한도
한도는 두 축으로 셉니다 — 토큰마다 하루 호출 수를,
회사마다 한 달 호출 수를 셉니다.
하루 축을 넘으면 -32003,
한 달 축을 넘으면 -32004 가 돌아오고,
두 카운터는 한국 시간 기준으로 각각 자정과 매월 1일에 0 으로 돌아갑니다.
토큰을 새로 발급하면 하루 카운터는 그 토큰 것으로 새로 세지만,
한 달 카운터는 회사 단위라 그대로 이어서 셉니다.
어느 축에 걸렸는지는 돌아온 코드로 가르세요.
도구 목록과 권한 범위는 어디서 보나
이 면은 연결까지를 맡습니다.
도구가 무엇을 하고 어떤 permission 을 요구하는지,
되돌리기 어려운 작업에 확인 절차가 어떻게 붙는지는 아래 세 곳이 갖고 있습니다.
앞의 둘은 사람이 읽는 문서이고,
마지막 하나는 프로그램이 그대로 받아 쓰는 JSON 입니다.
도구 수와 권한 표기는 세 곳이 같은 레지스트리에서 나오므로 서로 어긋나지 않습니다.