MCP·Skill 설치와 설정 — 레퍼런스

MCP 서버와 Agent Skill을 Claude Code·Claude Desktop·API에 등록하는 방법을 한곳에 정리한 레퍼런스 | 공식 문서: modelcontextprotocol.io

대상 버전Claude Docs · Claude Code 2026-06 기준 (MCP 스펙 2025-11-25 / 프로토콜 2025-06-18)

참조 문서 URLmodelcontextprotocol.io · code.claude.com/docs/en/skills

문서 수집일2026-06-27

버전 확인 방법claude --version, claude mcp list, claude --debug(Skill YAML 파싱 확인)

개정 시 확인 사항MCP 스펙 버전(전송 방식·인증), Claude Code의 claude mcp 서브커맨드, Skill frontmatter 키 변동을 공식 문서에서 재확인

설치 경로 지도

MCP는 "서버를 어디에 등록하느냐", Skill은 "폴더를 어디에 두느냐"가 설치의 핵심이다. 같은 도구라도 등록 위치(스코프)에 따라 나에게만 보일지, 팀 전체가 공유할지가 갈린다. 아래 트리는 두 방식의 설치 경로를 한눈에 비교한다.

설치 경로
├── MCP 서버                                  외부 시스템 연결 — 서버 프로세스 등록
│   ├── claude mcp add <name> -- <cmd>         Claude Code CLI (stdio·로컬)
│   ├── claude mcp add --transport http …      Claude Code CLI (원격 HTTP)
│   ├── .mcp.json                              프로젝트 루트, git 공유(팀 단위)
│   └── claude_desktop_config.json             Claude Desktop, 재시작 필요
└── Agent Skill                                절차·전문성 패키징 — 폴더 배치
    ├── ~/.claude/skills/<name>/SKILL.md       개인(사용자 전역)
    ├── .claude/skills/<name>/SKILL.md         프로젝트(git 공유)
    ├── /plugin install …                       플러그인·마켓플레이스
    └── betas + container.skills                Claude API / claude.ai 업로드

1. MCP — Claude Code CLI 설치

Claude Code에서는 claude mcp 서브커맨드로 서버를 등록·조회·삭제한다. 로컬 프로그램을 표준 입출력(stdio)으로 띄우는 방식과, 원격 엔드포인트에 HTTP로 연결하는 방식 두 가지가 있다. 등록 시 스코프(local/project/user)를 정해 가시 범위를 통제한다.

`claude mcp add` — stdio 로컬 서버 등록

로컬에서 실행할 명령과 인자를 -- 뒤에 적으면, Claude Code가 그 프로그램을 자식 프로세스로 띄워 stdio로 통신한다. 파일시스템·로컬 DB처럼 내 컴퓨터에서 도는 도구를 붙일 때 쓴다. -- 구분자가 Claude의 플래그와 서버 실행 명령을 분리한다.

claude mcp add myserver -- python /path/to/server.py
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/docs

`claude mcp add --transport http` — 원격 서버 등록

원격 SaaS·API를 Streamable HTTP로 연결할 때 사용한다. 명령 대신 URL을 지정하며, 필요하면 인증 헤더(Bearer 토큰, API 키 등)를 함께 넘긴다. 로컬 프로세스를 띄우지 않으므로 호스팅된 서버를 여러 환경에서 재사용하기 좋다.

claude mcp add --transport http github https://example.com/mcp
claude mcp add --transport http myapi https://api.example.com/mcp --header "Authorization: Bearer TOKEN"

`claude mcp list` — 등록 서버 목록

현재 설정에 등록된 모든 MCP 서버와 연결 상태를 출력한다. 등록이 제대로 됐는지, 어떤 스코프에 잡혀 있는지 빠르게 확인하는 첫 단계다.

claude mcp list

`claude mcp get` — 단일 서버 상세 조회

특정 서버 하나의 설정 상세(전송 방식, 명령/URL, 환경 변수, 스코프)를 보여준다. 연결이 안 될 때 설정값을 점검하는 용도다.

claude mcp get myserver

`claude mcp remove` — 서버 제거

등록된 서버를 설정에서 삭제한다. 더 이상 쓰지 않는 도구는 제거해 컨텍스트에 실리는 tool 정의를 줄이는 것이 좋다(토큰 비용 절감).

claude mcp remove myserver

스코프	저장 위치 / 가시 범위	언제 쓰나
`local`	현재 프로젝트, 나에게만 적용(개인 설정). 기본 스코프	실험용·개인 토큰이 들어간 서버를 나만 쓸 때
`project`	프로젝트 루트의 `.mcp.json`, git으로 팀 공유	팀원 모두가 같은 서버를 쓰도록 리포지토리에 박아둘 때
`user`	사용자 전역, 모든 프로젝트에서 보임	여러 프로젝트에서 공통으로 쓰는 개인 서버

💡 핵심 한 줄: 스코프는 --scope local|project|user로 지정한다 — 팀 공유가 목적이면 project, 개인 전역이면 user.

2. MCP — .mcp.json (프로젝트 공유)

프로젝트 스코프로 등록한 서버는 리포지토리 루트의 .mcp.json 파일에 기록된다. 이 파일을 git에 커밋하면 팀원이 리포지토리를 클론하는 것만으로 동일한 MCP 서버 구성을 공유받는다 — 설치 안내 문서 없이도 환경이 재현된다.

`.mcp.json` — 프로젝트 단위 서버 정의

최상위 mcpServers 객체 아래에 서버별 별칭을 두고, 각 별칭에 실행 명령·인자·환경 변수를 적는다. 구조는 Claude Desktop 설정과 같은 형식을 따른다. 커밋된 서버는 팀원이 프로젝트를 열 때 함께 로드된다.

{
  "mcpServers": {
    "myserver": {
      "command": "python",
      "args": ["./server.py"],
      "env": { "API_KEY": "..." }
    }
  }
}

팀 공유 파일이므로 env에 실제 비밀키를 평문으로 커밋하지 말 것 — 환경 변수 참조나 별도 시크릿 관리를 쓰고, 프로젝트 서버를 처음 로드할 때는 신뢰 여부를 확인하라.

3. MCP — Claude Desktop

Claude Desktop 앱은 CLI가 아니라 설정 JSON 파일을 직접 편집해 MCP 서버를 등록한다. 파일을 수정한 뒤에는 앱을 재시작해야 변경이 반영된다.

`claude_desktop_config.json` — 데스크톱 설정 파일

mcpServers 객체 아래에 별칭을 두고 command(실행 파일), args(인자 배열), env(환경 변수)를 지정한다. 파일 위치는 운영체제별로 다르다. 저장 후 앱을 완전히 종료했다 다시 열어야 서버가 로드된다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/docs"],
      "env": {}
    }
  }
}

운영체제	설정 파일 경로	적용 방법
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`	저장 후 앱 재시작
Windows	`%APPDATA%\Claude\claude_desktop_config.json`	저장 후 앱 재시작

💡 핵심 한 줄: 데스크톱은 파일 편집 + 재시작이 한 묶음이다 — 수정했는데 서버가 안 보이면 십중팔구 재시작을 빼먹은 것이다.

4. Skill — 로컬 설치

Agent Skill 설치는 별도 등록 명령이 없다. 정해진 디렉터리에 SKILL.md를 담은 폴더를 두기만 하면 Claude가 자동으로 발견한다. 개인 전역과 프로젝트 단위, 두 위치를 구분해 쓴다.

`~/.claude/skills/` — 개인(사용자 전역) Skill

홈 디렉터리 아래 ~/.claude/skills/<name>/SKILL.md에 두면 모든 프로젝트에서 그 스킬을 쓸 수 있다. 개인이 반복하는 워크플로를 어디서나 꺼내 쓰고 싶을 때 적합하다.

~/.claude/skills/
└── my-workflow/
    ├── SKILL.md          # name + description(필수) frontmatter + 본문
    ├── reference/        # (선택) 상세 문서 — 필요 시 로드
    └── scripts/          # (선택) 실행 스크립트

`.claude/skills/` — 프로젝트 Skill

프로젝트 루트의 .claude/skills/<name>/SKILL.md에 두고 git에 커밋하면 팀 전체가 같은 스킬을 공유한다. 조직의 전문성·규칙을 리포지토리와 함께 배포하는 표준 방법이다.

.claude/skills/
└── pdf-report/
    └── SKILL.md

SKILL.md는 YAML frontmatter(필수 name ≤64자 소문자·숫자·하이픈, description ≤1024자 "무엇을 + 언제 사용")와 마크다운 본문으로 이뤄진다. progressive disclosure 원칙상 본문은 500줄 이내로 간결하게 두고, 상세 내용은 reference/*.md로 분리해 필요할 때만 읽히게 한다.

💡 핵심 한 줄: Skill 설치 = 폴더 복사. 트리거가 안 되면 설치 위치보다 description의 트리거 단어를 먼저 점검하라(claude --debug로 YAML 파싱 확인).

5. Skill — 플러그인·마켓플레이스

직접 폴더를 만들지 않고, 공개된 마켓플레이스에서 스킬을 플러그인으로 내려받아 설치할 수도 있다. 플러그인의 skills/ 디렉터리에 담긴 스킬이 함께 설치된다.

`/plugin marketplace add` — 마켓플레이스 등록

스킬·플러그인이 모여 있는 저장소를 마켓플레이스 소스로 추가한다. 이후 그 소스에서 개별 스킬을 골라 설치할 수 있다.

/plugin marketplace add <repo>

`/plugin install` — 플러그인 스킬 설치

등록된 마켓플레이스에서 스킬을 지정해 설치한다. <skill>@<marketplace> 형식으로 출처를 명시한다.

/plugin install <skill>@<marketplace>

설치 위치	가시 범위	배포 방법
`~/.claude/skills/`	개인 — 모든 프로젝트	폴더 직접 배치
`.claude/skills/`	프로젝트 — 팀 공유	git 커밋
플러그인 `skills/`	마켓플레이스 구독자	`/plugin install`

플러그인·스킬은 임의 코드(스크립트)를 실행할 수 있다 — 신뢰된 출처의 마켓플레이스만 추가하고, 설치 전 SKILL.md와 번들 스크립트를 검토하라.

6. Skill — Claude API / claude.ai

코드 실행 환경을 쓰는 Claude API와 claude.ai에서도 스킬을 쓸 수 있다. API는 베타 헤더와 컨테이너 설정으로, claude.ai는 설정 화면 업로드로 등록한다.

`betas` + `container.skills` — Claude API 등록

API에서 스킬을 쓰려면 베타 헤더 skills-2025-10-02와 code-execution-2025-08-25를 켜고, 요청의 container.skills에 사용할 스킬을 나열한다. Anthropic 기본 스킬로 pptx·xlsx·docx·pdf가 제공된다. 커스텀 스킬은 client.beta.skills.create(files=...)로 업로드하고 versions.create로 버전을 관리한다.

betas=["skills-2025-10-02", "code-execution-2025-08-25"]
container.skills=[{ "type": "anthropic", "skill_id": "pptx" }]

# 커스텀 스킬 업로드
client.beta.skills.create(files=...)

`claude.ai` — Settings 업로드

claude.ai에서는 Settings → Skills에서 스킬 폴더를 zip으로 올리고 토글로 켜고 끈다. 코드 실행 기능이 포함된 플랜이 필요하다.

anthropic 기본 pptx · xlsx · docx · pdf

💡 핵심 한 줄: API는 베타 헤더 두 개가 전제다 — skills-2025-10-02 + code-execution-2025-08-25가 없으면 스킬이 동작하지 않는다.

참고 링크

📖 Model Context Protocol 공식 문서
📖 Claude Code — Skills 문서
⚙️ Agent Skills Overview (platform.claude.com)

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

MCP·Skill 설치와 설정 — 레퍼런스

설치 경로 지도

1. MCP — Claude Code CLI 설치

claude mcp add — stdio 로컬 서버 등록

claude mcp add --transport http — 원격 서버 등록

claude mcp list — 등록 서버 목록

claude mcp get — 단일 서버 상세 조회

claude mcp remove — 서버 제거