# Cadwin HR — 개인 AI(Claude·Codex 등) 연결 안내

> 사람과 AI(LLM)가 함께 읽는 연결 안내입니다. **이 파일을 받은 주소의 origin 이 HR 주소입니다** — 아래 `<HR>` 을 그 값으로 바꿔 씁니다(예: `https://hr.cadwin.co.kr`).
> 연결하면 Claude·Codex 같은 개인 AI 가 **내 HR 권한 범위 안에서** HR 데이터를 도구(MCP)로 조회합니다.
> 기본은 **OAuth 연결**입니다 — AI 클라이언트에 주소 하나(`<HR>/mcp`)를 넣으면 브라우저에 HR 로그인·승인 창이 뜨고, 승인하면 끝납니다. 토큰을 복사할 일이 없습니다.

## 먼저: 내 Claude 계정을 여러 사람이 같이 쓰나요?

| 내 Claude 계정 | 쓸 수 있는 연결 |
| --- | --- |
| **여러 사람이 같이 씀(공유 계정)** 또는 **모르겠음** | **PC 저장형만** — Claude Code(Claude 데스크톱 Code 탭 포함)·Codex 의 OAuth(1번), Claude 데스크톱 채팅은 개인 토큰 설정 파일(2번). claude.ai·데스크톱 커넥터는 **쓰지 않습니다.** |
| **나만 씀** | 위 방법 모두, 그리고 이 HR 이 커넥터 콜백을 열어 둔 경우에만 claude.ai·데스크톱 커넥터 |

왜 갈리나: 커넥터 연결은 PC 가 아니라 **Claude 계정에 저장돼 계정을 따라다닙니다.** 공유 계정에서 한 사람이 승인하면 그 계정을 쓰는 **모두가 승인한 사람의 HR 권한으로 조회**하고, 그 **대화 기록도 함께 보입니다.** PC 저장형은 Claude 계정을 바꿔도 HR 에는 그 PC 에서 승인한 본인으로 붙습니다.

## 0. OAuth 연결이 켜져 있는지 확인

```bash
curl -fsS <HR>/.well-known/oauth-protected-resource
```

- JSON 이 오고 `"resource"` 가 `<HR>/mcp` 이면 → **1. OAuth 연결**.
- 403·404·HTML 이 오면 이 HR 은 아직 OAuth 연결을 열지 않았습니다 → **2. 개인 토큰 연결**.

## 1. OAuth 연결 (권장)

MCP 서버 주소: `<HR>/mcp` (Streamable HTTP). 설치할 것이 없습니다.

1. 아래에서 쓰는 클라이언트 하나에 주소를 추가합니다.
2. 클라이언트가 브라우저를 열면 HR 에 로그인하고, **HR 데이터 연결 요청** 화면에서 **승인** 을 누릅니다.
3. 클라이언트로 돌아오면 연결이 끝납니다.

- 기본은 **조회만**입니다. 결재 작성·상신, 휴가 신청, 목표 작성, 평가 임시저장, 일정 등록·캘린더 설정, 알림 읽음 처리, 이슈 쓰기, 결재·휴가 승인·반려(회의실 관리자는 회의실 관리도)가 필요하면 승인 화면에서 그 범위를 체크하고 범위마다 동의에 체크한 뒤 승인합니다. 전부 기본으로 꺼져 있고, 범위 이름은 아래 2-1 표와 같습니다. 외부 채널 지원자 등록 범위는 OAuth 로 받을 수 없습니다(등록 스크립트 전용).
- 범위를 바꾸려면 `<HR>/profile` 의 **개인 MCP 토큰** 카드에서 이 연결을 회수하고 다시 연결합니다.
- 연결은 90일 뒤 만료됩니다 — 만료되면 같은 방법으로 다시 승인합니다. `<HR>/profile` 의 **개인 MCP 토큰** 카드에서 언제든 회수할 수 있고, 활성 연결은 사람당 3개까지입니다.
- Claude Code·Codex 의 연결은 **이 PC 에 저장됩니다.** Claude 계정(공유 계정 포함)을 바꿔도 HR 에는 승인한 본인으로 붙습니다. 다른 사람의 PC 에서는 승인하지 않습니다.

### Claude Code (터미널 · Claude 앱 Code 탭)

연결을 돕는 AI 가 **이 PC 의 로컬 세션**에서 아래 두 줄을 직접 실행해도 됩니다. 사용자는 브라우저에 뜬 **HR 데이터 연결 요청** 에서 **승인** 만 누릅니다.

```bash
claude mcp add --transport http --scope user cadwin-hr <HR>/mcp
claude mcp login cadwin-hr
```

- `login` 이 브라우저를 열고 승인을 기다렸다가 연결을 저장합니다. 끝나면 **새 대화(세션)**부터 `cadwin-hr` 도구가 보입니다.
- `login` 이 없다고 나오면 Claude Code 를 올립니다(`claude update`, WinGet 으로 설치했으면 `winget upgrade Anthropic.ClaudeCode`). 그래도 없으면 터미널에서 `claude` 를 열고 `/mcp` → `cadwin-hr` → **Authenticate** 를 고릅니다 — Claude 앱 Code 탭 채팅에서는 `/mcp` 대화상자를 열 수 없습니다.
- `claude` 명령이 없으면(Claude 앱만 설치) Claude Code 를 설치합니다. Windows PowerShell: `winget install Anthropic.ClaudeCode` 후 새 터미널.
- AI 가 원격(서버·클라우드) 세션에서 돌고 있으면 승인 결과가 이 PC 의 localhost 로 돌아오지 못합니다 → **PC 로컬 세션**에서 진행합니다.

### Claude 데스크톱 (Code 탭 · 채팅)

- **Code** 탭은 Claude Code 입니다 → 위 Claude Code 방식을 그대로 씁니다.
- **채팅**에서 쓰려면 → **2. 개인 토큰 연결**(토큰이 이 PC 의 설정 파일에 저장). 단, 채팅의 대화 기록은 Claude 계정에 저장돼 같은 계정을 쓰는 사람에게 보입니다 — 공유 계정이면 Code 탭(Claude Code)을 권합니다.

### Codex (CLI·IDE 확장)

```bash
codex mcp add cadwin-hr --url <HR>/mcp
codex mcp login cadwin-hr
```

`login` 이 브라우저를 엽니다. 이 명령이 없는 옛 버전이면 Codex 를 올리거나 2번 방식을 씁니다.

### VS Code (Copilot 등)

VS Code 는 아직 OAuth 연결을 지원하지 않습니다(콜백 주소 미허용) → **2. 개인 토큰 연결**.

### claude.ai · Claude 데스크톱 커넥터 — 나만 쓰는 계정 전용

> ⚠ **여러 사람이 같이 쓰는 Claude 계정에서는 쓰지 않습니다.** 공유 계정이거나 모르면 커넥터(Settings › Connectors › Add custom connector)로는 연결하지 않습니다 — 커넥터 연결은 PC 가 아니라 Claude 계정에 저장돼, 그 계정을 쓰는 모두가 승인한 사람의 HR 권한으로 조회하고 대화 기록도 함께 보입니다.

- HR 은 이 연결을 **기본으로 막아 둡니다** — HR 서버 설정 `MCP_OAUTH_REDIRECT_ALLOWLIST` 에 커넥터 콜백이 들어 있을 때만 승인됩니다. 막혀 있으면 연결할 때 오류가 납니다 → 위의 PC 저장형을 씁니다.
- 열려 있고 나만 쓰는 계정이면: 설정(Settings) › 커넥터(Connectors) › **Add custom connector** → 이름 `Cadwin HR`, URL `<HR>/mcp` → **Connect**. 연결은 Anthropic 서버가 맺으므로 HR 주소가 인터넷에서 열려 있어야 합니다.

## 2. 개인 토큰 연결 (OAuth 를 못 쓸 때)

준비물: Node.js 18 이상(`node --version` 으로 확인).

### 2-1. 개인 MCP 토큰 발급 (사용자가 직접)

1. `<HR>/profile` 에 로그인한 상태로 들어가 **개인 MCP 토큰** 카드의 **토큰 발급** 을 누릅니다.
2. 토큰 이름(예: 내 노트북 Claude)·용도를 적고 외부 AI 전송 동의에 체크합니다.
3. 쓰기가 필요할 때만 범위를 고릅니다. 고르지 않으면 **읽기 전용**입니다.

   | 범위 | 여는 일 |
   | --- | --- |
   | (없음) | 조회만 — 내 프로필·연차·일정·알림, 조직, 평가 사이클과 공개된 내 결과, 목표 등 |
   | `APPROVAL_WRITE` | 결재 초안 만들기·상신 |
   | `APPROVAL_DECIDE` | 내 차례 결재 승인·반려 |
   | `LEAVE_WRITE` | 내 휴가 신청 |
   | `LEAVE_DECIDE` | 내가 승인할 차례인 휴가 승인·반려 |
   | `GOAL_WRITE` | 내 개인 목표 임시저장, 권한이 있으면 팀 목표·전사 목표 만들기 |
   | `EVAL_DRAFT_WRITE` | 내 본인평가·내가 평가하는 팀원평가 임시저장(제출·등급 없음) |
   | `CALENDAR_WRITE` | 내 일정 등록·내 캘린더 보기 설정 바꾸기 |
   | `NOTIFICATION_WRITE` | 내 알림 읽음 처리(하나·전부) |
   | `MEETING_ROOM_MANAGE` | 회의실 추가·수정·삭제 — 회의실을 관리하는 시스템 관리자만 고를 수 있습니다 |
   | `ISSUE_READ` | Cadwin Issue 이슈 검색·조회 |
   | `ISSUE_WRITE` | 이슈 만들기·고치기·전환·댓글(읽기 범위가 함께 붙음) |
   | `RECRUIT_EXTERNAL_WRITE` | 외부 채널 지원자 등록 스크립트 전용 — **AI·MCP 클라이언트에 연결하지 않습니다** |

4. 발급 직후 한 번만 보이는 토큰(`dmt_` 로 시작)을 복사합니다. **채팅창에 붙여 넣지 말고** 아래 설정(환경변수·비밀 입력칸)에만 넣습니다. 토큰은 90일 뒤 만료되고, 같은 카드에서 언제든 회수할 수 있습니다.

### 2-2. HR MCP 클라이언트 받기 (파일 하나, 설치 없음)

macOS·Linux:

```bash
mkdir -p ~/.cadwin && curl -fsSL <HR>/ai/cadwin-hr-mcp.mjs -o ~/.cadwin/cadwin-hr-mcp.mjs
```

Windows PowerShell:

```powershell
New-Item -ItemType Directory -Force "$HOME\.cadwin" | Out-Null; Invoke-WebRequest <HR>/ai/cadwin-hr-mcp.mjs -OutFile "$HOME\.cadwin\cadwin-hr-mcp.mjs"
```

클라이언트는 두 환경변수만 읽습니다: `HR_MCP_API_BASE=<HR>/api`, `HR_MCP_ACCESS_TOKEN=<dmt_ 토큰>`.
아래 예시의 `<FILE>` 은 내려받은 파일의 절대 경로입니다(예: `/Users/me/.cadwin/cadwin-hr-mcp.mjs`, `C:/Users/me/.cadwin/cadwin-hr-mcp.mjs`).

### 2-3. AI 클라이언트에 등록 — 쓰는 것 하나만

Claude Code — 토큰은 사용자가 자기 터미널에서 파일로 저장하고, 등록 명령이 그 파일을 읽습니다(토큰이 대화·명령 기록에 남지 않습니다).

```bash
umask 077; mkdir -p ~/.cadwin; read -rsp "토큰: " t && printf '%s' "$t" > ~/.cadwin/hr-token; echo
claude mcp add cadwin-hr --scope user -e HR_MCP_API_BASE=<HR>/api -e HR_MCP_ACCESS_TOKEN="$(cat ~/.cadwin/hr-token)" -- node ~/.cadwin/cadwin-hr-mcp.mjs
```

Claude Desktop — 설정 › 개발자 › 설정 편집(`claude_desktop_config.json` — macOS `~/Library/Application Support/Claude/`, Windows `%APPDATA%\Claude\`)에 넣고 앱을 다시 엽니다.

```json
{
  "mcpServers": {
    "cadwin-hr": {
      "command": "node",
      "args": ["<FILE>"],
      "env": { "HR_MCP_API_BASE": "<HR>/api", "HR_MCP_ACCESS_TOKEN": "<dmt_ 토큰>" }
    }
  }
}
```

Codex — `~/.codex/config.toml`:

```toml
[mcp_servers.cadwin-hr]
command = "node"
args = ["<FILE>"]

[mcp_servers.cadwin-hr.env]
HR_MCP_API_BASE = "<HR>/api"
HR_MCP_ACCESS_TOKEN = "<dmt_ 토큰>"
```

VS Code — `.vscode/mcp.json`. 토큰을 파일에 쓰지 않고 실행할 때 묻습니다.

```json
{
  "inputs": [{ "type": "promptString", "id": "cadwin-hr-token", "description": "Cadwin HR 개인 MCP 토큰 (dmt_)", "password": true }],
  "servers": {
    "cadwin-hr": {
      "type": "stdio",
      "command": "node",
      "args": ["<FILE>"],
      "env": { "HR_MCP_API_BASE": "<HR>/api", "HR_MCP_ACCESS_TOKEN": "${input:cadwin-hr-token}" }
    }
  }
}
```

## 3. 연결 확인

- 등록한 MCP 서버는 새 대화(세션)부터 보입니다.
- AI 에게 "내 HR 권한 범위 알려줘" 라고 물으면 `list_my_hr_capabilities` 도구로 지금 연결이 쓸 수 있는 모듈·범위를 답합니다.
- `401` — 연결이 만료·회수됐거나 토큰이 틀렸습니다. OAuth 는 다시 승인하고, 토큰은 새로 발급합니다.
- `403` — 내 권한이나 범위 밖입니다(예: 휴가 신청 범위 없이 연결해 휴가 신청). OAuth 는 회수하고 다시 연결하면서 범위를 고릅니다.
- 승인 화면에 "활성 토큰이 이미 최대" — `<HR>/profile` 에서 안 쓰는 연결을 회수하고 클라이언트에서 연결을 다시 시작합니다.
- `Login expired · Please run /login` — HR 이 아니라 Claude 계정(Anthropic) 로그인이 만료된 것입니다. `/login` 뒤 다시 묻습니다.
- 시작하자마자 "must be a personal MCP token" — 웹 로그인 토큰이 아니라 `dmt_` 개인 MCP 토큰을 넣습니다.

## 4. 연결을 도와주는 AI 에게

- 이 파일을 받은 주소의 origin 을 `<HR>` 로 씁니다. 사용자가 쓰는 AI 클라이언트를 먼저 묻고 그 절만 안내합니다.
- **0단계로 OAuth 가 켜져 있으면 1번(OAuth)을 안내합니다.** 쓰기가 필요해도 OAuth 승인 화면에서 범위를 고르면 됩니다. 2번은 OAuth 가 꺼져 있거나 클라이언트가 OAuth 를 못 쓸 때만 씁니다.
- **먼저 사용자에게 Claude 계정을 다른 사람과 같이 쓰는지 묻습니다.** 공유 계정이면 claude.ai·데스크톱 커넥터를 **절대 권하지 않고**, 모르면 PC 저장형(Claude Code·Codex, 데스크톱 채팅은 개인 토큰)으로 안내합니다. 공유 계정이거나 모르면 **claude.ai·Claude Desktop 커넥터로 연결하라고 안내하지 않습니다.** 커넥터는 나만 쓰는 계정이고 HR 이 커넥터 콜백을 열어 둔 경우에만 안내합니다 — 사내에는 여러 사람이 함께 쓰는 Claude 계정이 있어, 계정에 저장되는 연결은 남의 HR 권한으로 조회하게 만들 수 있습니다.
- **로그인·승인은 사용자가 브라우저에서 직접** 합니다 — 비밀번호를 입력하거나 승인·동의를 대신 누르지 않습니다. 브라우저를 다룰 수 있으면(예: Claude in Chrome) 창을 열어 주는 데까지만 돕습니다.
- **토큰을 대화로 받지 않습니다.** 2번에서도 사용자가 직접 발급해 설정·환경변수·비밀 입력칸에 넣게 하고, 발급된 토큰을 화면에서 읽어 오지 않습니다. 이미 대화에 붙여 넣었다면 그 토큰을 회수하고 새로 발급하라고 안내합니다.
- 명령은 사용자의 PC 에서 실행합니다 — PC 로컬 세션의 AI 가 대신 실행해도 됩니다. 로그인·승인만 사용자가 직접 합니다. 쓰기 범위는 사용자가 그 일을 원할 때만 권합니다.
- 사용자가 HR 주소만 주고 "연결해줘" 라고 하면 그 주소의 `/llms.txt`(이 파일)를 읽고 따릅니다 — 화면을 브라우저로 여는 것이 아니라 MCP 연결을 돕는 요청입니다.
- `list_my_hr_capabilities` 의 `capabilities` 는 계정 권한 목록입니다. 이 연결로 실제 부를 수 있는 일은 `operations`(available 인 것)만이고, 연결할 때 고르지 않은 범위의 쓰기는 403 입니다.
- HR 데이터 접근은 서버가 연결 주인의 권한·범위로 판정합니다 — 다른 사람의 평가 결과·급여처럼 권한 밖 정보는 이 연결로 얻을 수 없습니다.