MCP·Skill 운영 레퍼런스

디버깅 · 보안 · 토큰 비용 · 팀 배포를 한곳에서  |  공식 문서: modelcontextprotocol.io · Claude Code Skills

운영 관점 지도

운영은 "만들기"가 아니라 "굴리기"의 영역이다. MCP 서버든 Agent Skill이든, 실제로 팀에 들이고 나면 네 가지 질문이 반복된다. 왜 안 도나(디버깅), 믿어도 되나(보안), 얼마나 무거운가(토큰 비용), 어떻게 나누나(배포). 아래 지도는 그 네 축을 MCP와 Skill 양쪽에 걸쳐 한눈에 보여준다.

운영(Operations)
├── 디버깅                       왜 동작/트리거가 안 되나
│   ├── MCP                        Inspector · claude mcp list/get · mcp*.log
│   └── Skill                      description 점검 · claude --debug · 직접 호출
├── 보안                         실행해도 안전한 출처인가
│   ├── MCP                        prompt injection · OAuth · SSRF · 세션 하이재킹
│   └── Skill                      임의 코드 실행 · 데이터 탈출 · 번들 검사
├── 토큰·컨텍스트 비용          상시 점유 vs 메타만
│   ├── MCP                        tool 정의(inputSchema) 매 요청 상주
│   └── Skill                      Level1 메타(~100토큰)만 상시
└── 팀 배포·버전              어떻게 공유하고 갱신하나
    ├── MCP                        .mcp.json · 원격 서버 호스팅
    └── Skill                      git(.claude/skills) · 플러그인 · API versions

1. MCP 디버깅

MCP 서버는 Claude와 별도 프로세스로 돈다. 그래서 문제가 생겨도 모델 응답만 봐서는 원인을 알기 어렵다. 핵심은 서버를 모델에서 떼어내 단독으로 검사하는 것이다. tool 목록은 제대로 노출되는지, 인자 스키마는 맞는지, 연결 자체가 끊긴 건 아닌지를 단계적으로 좁혀 간다.

npx @modelcontextprotocol/inspector — 서버를 단독으로 띄워 검사

MCP Inspector는 서버를 모델 없이 직접 띄워 tools/list, resources, prompts를 브라우저 UI에서 확인하고 호출까지 해보는 공식 도구다. "Claude가 이 tool을 못 본다"는 증상이 모델 문제인지 서버 문제인지부터 가른다. 서버를 실행할 명령을 그대로 인자로 넘기면 된다.

npx @modelcontextprotocol/inspector node ./build/server.js
npx @modelcontextprotocol/inspector python -m my_server

Inspector에서 tool이 정상적으로 뜨고 호출이 되는데 Claude에서만 안 보인다면, 원인은 서버가 아니라 등록(스코프·경로)이나 클라이언트 쪽에 있다.

claude mcp list / claude mcp get — 등록 상태와 연결 확인

Claude Code에 어떤 서버가 어떤 스코프(local·project·user)로 등록됐는지, 연결은 살아 있는지 확인한다. list로 전체를 훑고, 의심 가는 서버는 get <name>으로 명령·인자·전송 방식 같은 상세 설정을 들여다본다. 잘못 등록된 서버는 claude mcp remove로 지우고 다시 추가한다.

claude mcp list
claude mcp get github
claude mcp remove github

~/Library/Logs/Claude/mcp*.log — 런타임 로그 추적

Claude Desktop의 MCP 로그는 위 경로(macOS)에 쌓인다. 서버 시작 실패, 핸드셰이크(initialize) 오류, stdio 파이프 깨짐 같은 저수준 문제는 모델 화면이 아니라 이 로그에 남는다. 연결이 "조용히" 안 되는 경우 가장 먼저 열어볼 곳이다.

💡 핵심 한 줄: 디버깅 순서는 "Inspector로 서버 단독 검증 → claude mcp list/get으로 등록 확인 → mcp*.log로 런타임 추적"이다. 모델을 의심하기 전에 서버를 떼어내 보라.

2. MCP 보안

MCP는 외부 시스템을 모델에 직접 연결하는 통로다. 그만큼 신뢰 경계가 넓어진다. 서드파티 서버 하나를 등록하는 순간, 그 서버가 노출하는 tool 설명과 응답이 모델의 행동에 영향을 준다. 아래는 공식 문서가 짚는 대표 위협과 완화책이다.

3. Skill 디버깅

Skill 디버깅의 90%는 "왜 트리거가 안 되나"다. Skill은 description의 메타데이터만 상시 로드되고, Claude가 그 description을 보고 "지금 이 스킬을 써야겠다"고 판단해야 본문(SKILL.md)이 열린다. 즉 트리거 실패는 대개 description 문제다.

description 점검 — 트리거 실패의 1순위 원인

description에는 무엇을 하는지와 언제 써야 하는지가 모두 들어가야 한다. 사용자가 실제로 쓸 법한 트리거 단어를 3인칭으로, 구체적으로 적는다. "문서를 다룬다" 같은 모호한 문장보다 "PDF에서 표를 추출하거나 양식을 채울 때 사용한다"처럼 상황을 박아 넣어야 모델이 매칭한다.

# 약함 — 언제 쓸지 불명확
description: Helps with spreadsheets.

# 강함 — 트리거 단어 + 사용 시점이 구체적
description: Reads, writes, and analyzes Excel (.xlsx) files.
  Use when the user asks to summarize spreadsheet data,
  build pivot tables, or generate .xlsx reports.

claude --debug — YAML frontmatter 파싱 확인

frontmatter의 YAML이 깨졌거나 name이 규칙(64자 이하·소문자·숫자·하이픈, anthropic/claude 예약어 회피)에 어긋나면 Skill이 아예 로드되지 않는다. claude --debug로 실행하면 어떤 스킬이 파싱·로드됐는지, 어디서 막혔는지가 출력된다. "분명 폴더에 넣었는데 안 보인다"면 여기부터 본다.

claude --debug

직접 호출 테스트 — 트리거와 동작을 분리해 확인

Skill을 직접(명시적으로) 불러 실행해보면, 문제가 트리거 매칭에 있는지 본문·스크립트 동작에 있는지를 가른다. 직접 호출했을 때 정상 동작한다면 description을 손보면 되고, 직접 호출에서도 실패한다면 SKILL.md 본문이나 번들 스크립트를 봐야 한다. user-invocable·disable-model-invocation 같은 frontmatter 키로 호출 방식을 통제할 수 있다.

💡 핵심 한 줄: 트리거가 안 되면 description, 로드가 안 되면 claude --debug, 동작이 안 되면 직접 호출로 본문·스크립트를 검증하라.

4. Skill 보안

Skill은 마크다운만 있는 것처럼 보이지만, 번들에 스크립트(scripts/*.py 등)를 담을 수 있고 그 스크립트는 코드 실행 환경에서 실제로 돈다. 따라서 "신뢰된 출처만 설치한다"가 절대 원칙이다. 외부에서 받은 Skill은 본문과 번들 파일을 사람이 직접 읽어보기 전에는 켜지 않는다.

특히 disable-model-invocation은 모델이 description만 보고 멋대로 스킬을 발동하는 것을 차단한다. 파괴적 작업이나 검증이 끝나지 않은 스킬은 이 키로 자동 호출을 끄고, 사람이 명시적으로 부를 때만 돌게 두는 편이 안전하다.

5. 토큰·컨텍스트 비용

운영에서 자주 간과되는 비용이 컨텍스트 점유다. MCP와 Skill은 "상시 차지하는 토큰"의 양이 근본적으로 다르다. 이 차이를 모르면 서버를 잔뜩 등록해놓고 매 요청 컨텍스트가 새는 줄도 모르게 된다.

MCP tool 정의 상주 — 매 요청 컨텍스트 점유

MCP tool은 정의(이름·설명·inputSchema)가 매 요청마다 모델 컨텍스트에 실려 들어간다. 등록된 서버의 tool이 많을수록, 스키마가 복잡할수록 상시 비용이 커진다. 쓰지 않는 서버·tool은 비활성화하는 것이 직접적인 절약이다.

Skill 메타데이터만 상시 — progressive disclosure

Skill은 Level1 메타데이터(name + description, 스킬당 약 100토큰)만 상시 로드된다. 본문(SKILL.md, 보통 5K 토큰 미만)은 트리거됐을 때, 번들 리소스(Level3)는 실제로 필요할 때만 읽힌다. 게다가 스크립트는 코드 전체가 아니라 실행 출력만 컨텍스트에 들어온다. 그래서 스킬을 많이 두어도 상시 비용은 메타데이터 합에 그친다.

💡 핵심 한 줄: MCP는 "연결만 해둬도 비용", Skill은 "써야 비용". 상시 컨텍스트가 빡빡하면 안 쓰는 MCP tool부터 끄고, SKILL.md는 본문을 얇게 유지하라.

6. 팀 배포·버전

혼자 쓸 때와 팀에 배포할 때의 운영은 다르다. 핵심은 "설정을 어떻게 공유하고, 버전을 어떻게 고정하느냐"다. MCP와 Skill은 배포 단위가 다르므로 방법도 갈린다.

MCP .mcp.json / 원격 서버 — 등록 정보를 공유

프로젝트 스코프 서버는 저장소 루트의 .mcp.json에 적어 git으로 공유한다. 팀원이 같은 프로젝트를 열면 동일한 서버 구성이 적용된다. 다만 MCP 서버 자체는 별도로 호스팅·실행돼야 하므로, 원격(Streamable HTTP) 서버라면 엔드포인트·인증을 함께 운영해야 한다.

claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp add --transport http issues https://mcp.example.com/issues
# 프로젝트 스코프 설정은 .mcp.json 에 기록되어 git으로 공유

Skill git(.claude/skills) / 플러그인 / API versions — 폴더째 배포

Skill은 폴더가 곧 배포 단위다. 프로젝트 스킬을 .claude/skills/<name>/에 두고 git 커밋하면 팀 전체가 같은 스킬을 쓴다. 더 넓게 공유할 때는 플러그인 마켓플레이스로 배포한다. API에서는 skills.create로 올리고 versions.create로 버전을 고정·갱신한다.

# 프로젝트 공유 — 폴더를 git에 커밋
.claude/skills/report-writer/SKILL.md

# 플러그인 마켓플레이스로 배포
/plugin marketplace add my-org/skills-repo
/plugin install report-writer@my-org

MCP 공유 Skill 폴더 플러그인 API 버전

참고 링크

• 📖 Model Context Protocol — 공식 문서
• 🛡️ MCP Security Best Practices (modelcontextprotocol.io)
• ⚙️ Claude Code — Agent Skills
• 🧩 Agent Skills Overview (platform.claude.com)

Claude Docs · Claude Code 2026-06 기준 (MCP 스펙 2025-11-25 / 프로토콜 2025-06-18) | 문서 수집일 2026-06-27