incident-assistant — MCP "Hello World"

MCP(모델 컨텍스트 프로토콜) 테스트 서버로, MCP 책/강좌의 "incident response" 실습을 따라 만들었습니다. 차이점은 클라이언트로 Gemini CLI 대신 Claude Code를 사용한다는 점입니다.

이 서버는 프로덕션 시스템의 알림 대시보드를 시뮬레이션하며 다음을 제공합니다:

• 리소스(resource://incidents/active) — 활성 알림 목록(목 데이터).

• 도구(resolve_incident) — 알림을 해결하기 위해 서비스를 "재시작"하며, 80%의 시뮬레이션된 성공률을 가집니다(실패 경로도 확인할 수 있습니다).

소스: src/index.ts

스택

• @modelcontextprotocol/sdk — TypeScript/Node용 공식 MCP SDK.

• stdio 전송 방식(클라이언트가 서버를 하위 프로세스로 실행하고 stdin/stdout으로 통신).

• TypeScript를 dist/로 컴파일(tsconfig.json 참조).

1. 설치 및 빌드

npm install
npx tsc

이 명령은 src/index.ts를 dist/index.js(서버를 시작하는 엔트리 포인트)로 컴파일합니다.

참고: 서버 내부 로깅에는 의도적으로 console.error를 사용합니다. stdout은 MCP JSON-RPC 프로토콜용으로 예약되어 있으므로, console.log를 사용하면 클라이언트와의 통신이 깨집니다.

2. Claude Code에 서버 등록

책(Gemini CLI의 settings.json 사용)과 달리, Claude Code에서는 로컬 MCP 서버를 claude mcp add 명령으로 등록합니다:

cd /absolute/path/to/incident-assistant
claude mcp add --scope project incident-assistant -- node /absolute/path/to/incident-assistant/dist/index.js

핵심 사항:

• --는 claude mcp add 자체의 플래그와 서버를 시작하는 실제 명령을 구분합니다.

• dist/index.js의 절대 경로를 사용합니다(상대 경로는 .mcp.json의 위치가 아닌 claude가 실행된 디렉터리를 기준으로 해석됩니다).

• --scope project는 설정을 저장소 루트의 .mcp.json에 저장합니다(git으로 버전 관리 가능). 대안: --scope local(나만 사용, 공유되지 않음) 또는 --scope user (모든 프로젝트에서 사용 가능, ~/.claude.json에 저장).

이렇게 하면 사용자 머신의 절대 경로가 포함된 로컬 .mcp.json이 생성됩니다. 이 경로는 사용자 환경에 따라 다르므로 .mcp.json 자체는 gitignore에 포함됩니다. 대신 저장소에는 플레이스홀더 경로가 포함된 .mcp.json.example이 제공됩니다:

{
  "mcpServers": {
    "incident-assistant": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/incident-assistant/dist/index.js"]
    }
  }
}

3. 서버 승인

.mcp.json은 프로젝트 파일이므로(공유 저장소에서 올 수 있음), Claude Code는 처음에 명시적 승인을 요청합니다:

claude

시작 시 incident-assistant에 대한 신뢰 프롬프트가 표시됩니다. 프로젝트당 한 번만 승인하면 됩니다(이후 서버의 명령/인수가 변경되지 않는 한).

4. 확인

claude mcp list
claude mcp get incident-assistant

승인 후 기대되는 출력:

incident-assistant: node /absolute/path/to/incident-assistant/dist/index.js - ✔ Connected

claude 세션 내에서 /mcp를 입력하면 서버가 제공하는 도구/리소스 목록이 표시됩니다.

5. 데모 — 실제 결과

에이전트에 대한 프롬프트: "치명적인 알림이 있나요? 있다면 수정을 시도하고 결과를 알려주세요"

에이전트는:

1. 사용 가능한 MCP 리소스를 나열하고(listMcpResources) resource://incidents/active를 찾았습니다.

2. 해당 리소스를 읽고(readMcpResource) 목 알림을 확인했습니다:

   ID	Service	Status	Message
   ALRT-001	auth-api	🔴 치명적	메모리 누수 감지됨
   ALRT-002	payment-gateway	🟡 경고 (치명적 아님)	지연 시간 > 500ms

3. 치명적인 알림은 ALRT-001뿐임을 확인하고 serviceName: "auth-api"로 resolve_incident 도구를 호출했습니다.

4. 결과:

   ✅ 해결됨: auth-api가 메모리 누수를 해결하기 위해 정상적으로 재시작되었습니다(ALRT-001, 치명적). 재시작 성공.

   ⚠️ 건드리지 않음: payment-gateway는 여전히 경고(지연 시간 > 500ms)를 표시하지만, 치명적이지 않으므로 그대로 두었습니다.

   에이전트의 메모: 재시작은 증상을 해결할 뿐 근본 원인을 해결하는 것은 아닙니다 — 누수가 재발하지 않는지 auth-api 메모리를 계속 관찰할 가치가 있습니다.

5. *"payment-gateway도 재시작하세요"*라고 명시적으로 요청하면 에이전트는 serviceName: "payment-gateway"로 resolve_incident를 다시 호출합니다(정확한 결과는 80%의 시뮬레이션된 성공률에 따라 달라지므로 여기에 기록되지 않습니다 — ✅ 성공 또는 ❌ 실패로 반환될 수 있습니다).

이로써 전체 루프가 확인됩니다: MCP 클라이언트(Claude Code) → 리소스/도구 검색 → 리소스 읽기 → 결정 → 도구 호출 → 결과.

크레딧

이 실습은 maliksahil/mcp-incident-assistant을 기반으로 학습했습니다. 원본 워크스루는 MCP 클라이언트로 Gemini CLI를 사용하지만, 이 저장소는 동일한 서버를 Claude Code와 함께 사용하도록 적용했습니다.

참고 사항 / 주의사항

• 서버는 WSL에서 실행됩니다. 이 설정에서는 Claude Code도 WSL 터미널에서 실행되므로 .mcp.json의 경로는 기본 Linux 경로(예: /home/<user>/...)이며 Windows UNC 경로 (\\wsl.localhost\...)가 아닙니다.

• src/index.ts를 수정한 경우 변경 사항을 적용하려면 다시 빌드(npx tsc)해야 합니다 — 서버는 .ts 파일이 아닌 dist/index.js에서 시작됩니다.

• resolve_incident는 의도적으로 80%의 시뮬레이션된 성공률(Math.random() > 0.2)을 가지므로, 에이전트가 성공과 실패(isError: true) 경우를 모두 어떻게 처리하는지 관찰할 수 있습니다.