Model Context Protocol로 파일시스템·GitHub·DB·Slack을 AI 에이전트에 노출. 셋업·디버깅·보안.

**Model Context Protocol (MCP)**는 AI 에이전트에게 외부 도구·데이터를 표준화된 방식으로 노출하는 프로토콜이다. Anthropic이 발표한 오픈 스펙으로, Claude Code·Cursor·Continue 등 주요 도구가 같은 인터페이스를 공유한다.

쉽게 말해: "GPT나 Claude가 내 파일시스템·DB·GitHub를 직접 만지게 하고 싶은데 매번 API wrapper 짜기 싫음" 을 해결하는 표준.

이 가이드는 MCP의 핵심 개념부터 자주 쓰는 서버 셋업, 디버깅, 보안까지.

TL;DR

MCP는 stdio/SSE 기반 RPC — JSON-RPC 메시지로 도구를 노출
공식 서버 풀: filesystem, GitHub, Slack, Postgres, Puppeteer 등 — @modelcontextprotocol/server-*
클라이언트 설정 1곳: Claude Code는 ~/.claude/settings.json, Cursor는 Settings UI → 같은 JSON 스키마
보안 1번 룰: read-only 서버 위주, 쓰기 가능 서버는 명시적 화이트리스트 폴더만

사전 조건

Node.js 20+ (npx 사용)
MCP 호환 클라이언트 1개 — Claude Code 또는 Cursor
사용할 서비스의 API 토큰 (GitHub PAT, Slack 등)

1. MCP 개념 30초

용어	의미
호스트	AI 에이전트 (Claude Code, Cursor 등)
서버	도구·리소스를 노출하는 프로세스 (filesystem, GitHub 등)
클라이언트	호스트가 각 서버와 통신하기 위해 띄우는 어댑터
Transport	stdio (로컬, 자식 프로세스) 또는 SSE (HTTP 원격)
Tool	서버가 노출하는 함수 — AI가 호출 가능
Resource	서버가 노출하는 데이터 — AI가 읽기 가능
Prompt	서버가 제공하는 프롬프트 템플릿

2. Claude Code에서 MCP 추가

2.1 설정 파일

~/.claude/settings.json:

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

명령 인자 = 노출할 디렉토리. 화이트리스트 — 여기 안 적은 경로는 접근 불가.
절대 경로 권장. ~/ 같은 셸 확장은 동작 안 함.

2.2 Claude Code 재시작

# 기존 세션 종료 후
claude

2.3 확인

Claude Code 안에서:

어떤 도구를 사용할 수 있어?

filesystem MCP의 read_file, write_file, list_directory 등이 나오면 성공.

3. Cursor에서 MCP 추가

Settings (⌘,) → Features → MCP → Add Server. JSON:

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

같은 스키마. Claude Code와 같은 설정을 공유 가능 — ~/.claude/settings.json을 복붙하면 끝.

4. 자주 쓰는 서버 6종

4.1 Filesystem

"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
}

파일 읽기·쓰기·검색. 노출 경로 화이트리스트 강제.

4.2 GitHub

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}

Issues·PR·코드 검색. PAT 권한은 필요한 최소만 (repo, read:user).

4.3 Slack

"slack": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-slack"],
  "env": {
    "SLACK_BOT_TOKEN": "xoxb-...",
    "SLACK_TEAM_ID": "T..."
  }
}

채널 메시지 조회·발신. bot token 권장 (user token 대신).

4.4 PostgreSQL (read-only)

"postgres": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-postgres",
    "postgresql://readonly_user:pass@localhost/mydb"
  ]
}

read-only 유저로 연결 — AI가 임의 쿼리 실행 가능하니 권한 분리 필수.

4.5 Puppeteer

"puppeteer": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
}

실제 브라우저 자동화. 스크린샷·DOM 조작·JS 실행.

4.6 SQLite

"sqlite": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db.sqlite"]
}

로컬 SQLite 분석에 좋음.

5. 1Password로 시크릿 관리

JSON에 토큰 평문 직접 작성 금지. multi-os/password-manager 패턴 활용:

옵션 A — chezmoi 템플릿

~/.claude/settings.json 자체를 chezmoi 관리에 두고 {{ onepasswordRead "op://..." }} 사용.

옵션 B — 래퍼 스크립트

# ~/bin/mcp-github.sh
#!/bin/bash
export GITHUB_PERSONAL_ACCESS_TOKEN="$(op item get GitHub --fields token --reveal)"
exec npx -y @modelcontextprotocol/server-github

settings.json:

"github": {
  "command": "/Users/me/bin/mcp-github.sh"
}

op CLI가 GUI biometric로 자동 unlock — 매끄럽다.

6. 커스텀 MCP 서버 만들기

10분 안에 자기 도구 노출 가능. Node.js 예시 (my-server.js):

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
const server = new Server(
  { name: "my-tools", version: "0.1.0" },
  { capabilities: { tools: {} } }
);
 
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "echo",
      description: "Echo back input",
      inputSchema: {
        type: "object",
        properties: { msg: { type: "string" } },
        required: ["msg"],
      },
    },
  ],
}));
 
server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === "echo") {
    return { content: [{ type: "text", text: req.params.arguments.msg }] };
  }
  throw new Error(`Unknown tool: ${req.params.name}`);
});
 
await server.connect(new StdioServerTransport());

"my-tools": {
  "command": "node",
  "args": ["/Users/me/code/my-server.js"]
}

MCP SDK 공식 examples 참고.

7. 디버깅

도구가 안 나타남

클라이언트(Claude Code/Cursor) 완전 재시작
npx 실행 가능한지 — which npx / 노드 버전 20+
서버 로그 — Claude Code의 경우 시스템 로그 또는 stderr 확인

MCP Inspector

공식 디버깅 도구:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

브라우저에서 서버에 직접 RPC 호출 가능. 도구 정의·응답 시각화.

응답이 느림

첫 호출 시 npx -y 가 패키지 다운로드 — 한 번만 느림. 캐시 후 빠름
영구 설치: npm i -g @modelcontextprotocol/server-filesystem 후 command: "mcp-server-filesystem" 변경

8. 보안

화이트리스트 폴더만

filesystem 서버는 반드시 명시적 경로 인자만. 빠뜨리면 홈 디렉토리 전체 노출.

read-only DB 유저

Postgres/SQLite는 별도 readonly 유저 만들어서 연결. AI가 DROP TABLE 실행 못 하게.

토큰 권한 최소

GitHub PAT는 repo+read:user 정도. admin:org 같은 강한 권한 X.

환경변수 누출 방지

settings.json 자체를 git에 안 올리거나, 올리려면 chezmoi/secret 통합 (5장).

신뢰하지 않는 MCP 서버 금지

공식 @modelcontextprotocol/* 또는 직접 코드 검토 가능한 OSS만. 임의의 npm 패키지에 토큰 넘기지 말 것.

검증

settings.json 수정 후 Claude Code 재시작 → 사용 가능한 도구 보여줘 → 새 서버 도구 표시
루트 디렉토리 파일 목록 알려줘 (filesystem 서버 있을 때)
최근 PR 5개 요약해줘 (GitHub 서버)
MCP Inspector로 도구 정의 검증
의도적으로 화이트리스트 외 경로 시도 → 거부 확인

트러블슈팅

`npx -y` 패키지 못 찾음

@modelcontextprotocol/server-XXX 패키지명 오타 흔함. 공식 list 확인
사내 npm 레지스트리 사용 시 npmrc에서 공개 registry로 fallback 필요

Windows에서 경로 깨짐

JSON 안 \ 이스케이프 또는 / 사용:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/me/projects"]

Claude Code 안 인식

~/.claude/settings.json JSON 문법 오류 검사 — jq . ~/.claude/settings.json
다른 settings.json 위치(~/.claude.json, .claude/settings.json in project)와 혼동

응답에 누락된 도구

서버가 도구 정의 nondeterministic — restart 시 도구 목록 다를 수 있음. 서버 코드의 listTools 핸들러 deterministic하게.

토큰이 실수로 commit됨

즉시 토큰 회전 (GitHub → Personal access tokens → Revoke + 새로 발급). git history에서 제거는 git filter-repo 사용.

참고

Claude Code 셋업 — 호스트 셋업
Cursor 셋업 — 호스트 셋업
멀티 에이전트 워크플로 — 메인/서브 분담
비밀번호 매니저 — 토큰 보안 통합
Model Context Protocol 공식
공식 서버 풀

변경 이력

2026-05-12: 첫 작성. 개념 + 클라이언트 셋업 + 서버 6종 + 시크릿 관리 + 커스텀 서버 + 디버깅 + 보안 + 트러블슈팅 5종.

MCP 서버 셋업 — Claude Code · Cursor에 외부 도구 연결하기

TL;DR

사전 조건

1. MCP 개념 30초

2. Claude Code에서 MCP 추가

2.1 설정 파일

2.2 Claude Code 재시작

2.3 확인

3. Cursor에서 MCP 추가

4. 자주 쓰는 서버 6종

4.1 Filesystem

4.2 GitHub

4.3 Slack

4.4 PostgreSQL (read-only)

4.5 Puppeteer

4.6 SQLite

5. 1Password로 시크릿 관리

옵션 A — chezmoi 템플릿

옵션 B — 래퍼 스크립트

6. 커스텀 MCP 서버 만들기

7. 디버깅

도구가 안 나타남

MCP Inspector

응답이 느림

8. 보안

화이트리스트 폴더만

read-only DB 유저

토큰 권한 최소

환경변수 누출 방지

신뢰하지 않는 MCP 서버 금지

검증

트러블슈팅

`npx -y` 패키지 못 찾음

Windows에서 경로 깨짐

Claude Code 안 인식

응답에 누락된 도구

토큰이 실수로 commit됨

참고

변경 이력

댓글

MCP 서버 셋업 — Claude Code · Cursor에 외부 도구 연결하기

TL;DR

사전 조건

1. MCP 개념 30초

2. Claude Code에서 MCP 추가

2.1 설정 파일

2.2 Claude Code 재시작

2.3 확인

3. Cursor에서 MCP 추가

4. 자주 쓰는 서버 6종

4.1 Filesystem

4.2 GitHub

4.3 Slack

4.4 PostgreSQL (read-only)

4.5 Puppeteer

4.6 SQLite

5. 1Password로 시크릿 관리

옵션 A — chezmoi 템플릿

옵션 B — 래퍼 스크립트

6. 커스텀 MCP 서버 만들기

7. 디버깅

도구가 안 나타남

MCP Inspector

응답이 느림

8. 보안

화이트리스트 폴더만

read-only DB 유저

토큰 권한 최소

환경변수 누출 방지

신뢰하지 않는 MCP 서버 금지

검증

트러블슈팅

npx -y 패키지 못 찾음

Windows에서 경로 깨짐

Claude Code 안 인식

응답에 누락된 도구

토큰이 실수로 commit됨

참고

변경 이력

댓글

`npx -y` 패키지 못 찾음