오늘만 무료

CLAUDE.md 완전 정복 - MCP 연동 완전가이드

DB·GitHub·Slack·사내 API를 AI에 연결하는 설정과 보안

11시간전 brunch_membership's

MCP란 무엇인가

Model Context Protocol(MCP)은 Claude Code가 외부 툴이나 서비스와 연동하기 위한 표준 프로토콜입니다. MCP 서버를 연결함으로써 Claude Code의 능력을 데이터베이스 쿼리, API 호출, 브라우저 조작 등으로 확장할 수 있습니다.

Claude Code에는 기본으로 파일 조작과 Bash 실행 툴이 내장되어 있습니다. MCP는 여기에 추가 툴을 붙이는 확장 메커니즘입니다.

MCP 서버는 독립된 프로세스로 동작하며, Claude Code와 표준 입출력(stdio) 또는 HTTP로 통신합니다.

MCP 서버 설정

MCP 서버는 .claude/settings.json에 설정합니다. CLAUDE.md와는 별도 파일입니다.

{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
}
}
}

자주 쓰는 MCP 서버

PostgreSQL / MySQL

데이터베이스에 직접 쿼리를 실행할 수 있습니다.

{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
}
}
}

연결 후 "users 테이블의 최근 가입자 수를 알려줘"라고 말하기만 하면, Claude Code가 SQL을 실행하고 결과를 반환합니다. 스키마를 참조하여 타입 정의를 자동 생성하는 용도로도 자주 활용됩니다.

파일 시스템

프로젝트 디렉토리 외부 경로에도 접근이 필요할 때 사용합니다.

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

GitHub

GitHub의 Issue, PR, 레포지토리 정보에 접근합니다.

{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}

"이슈 #42의 요구사항을 보고 구현 계획을 세워줘"처럼, 이슈 내용을 직접 참조하면서 개발할 수 있습니다.

Slack

Slack 메시지 전송, 채널 목록 취득, 스레드 내용 참조가 가능합니다.

{
"mcpServers": {
"slack": {
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-slack"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
"SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
}
}
}
}

CLAUDE.md에서 MCP 툴 사용법을 지시한다

MCP 서버를 설정한 것만으로는 Claude Code가 언제, 어떻게, 어디까지 사용해야 할지 판단하지 못합니다. CLAUDE.md에서 사용 방침과 제약을 명시합니다.

## 외부 툴 (MCP)

### 데이터베이스 (postgres MCP)
- 개발 DB에는 MCP 경유로 쿼리 실행 가능
- SELECT 문만 실행 가능. INSERT/UPDATE/DELETE는 반드시 사전 확인 후 실행
- 프로덕션 DB 접속은 절대 금지
- 개인정보(이름, 전화번호, 이메일)가 포함된 조회는 로그에 출력하지 않는다

### GitHub (github MCP)
- Issue, PR 정보는 MCP 경유로 취득 가능
- Issue 생성, PR 코멘트는 자동으로 실행 가능
- PR 머지는 사용자가 직접 수동으로 실행한다

### Slack (slack MCP)
- #dev-team, #general 채널에 알림 전송 가능
- DM 전송은 금지
- 메시지 삭제·편집은 금지

### 사내 API (company-api MCP)
- 고객 정보 조회는 MCP 경유로 가능
- 데이터 수정(POST/PUT/DELETE)은 금지. 조회(GET)만

이 이층 구조가 핵심입니다. MCP 서버 설정(settings.json)에서 "접속처"를 정의하고,

CLAUDE.md에서 "사용 방침과 제약"을 정의합니다.

MCP 서버 자작

공개된 MCP 서버로 커버할 수 없는 사내 시스템과 연동할 때는 직접 MCP 서버를 구현합니다.

TypeScript 최소 구성

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
{ name: "my-tool", version: "1.0.0" },
{ capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({
tools: [
{
name: "greet",
description: "이름을 받아 인사를 반환한다",
inputSchema: {
type: "object",
properties: {
name: { type: "string", description: "이름" }
},
required: ["name"]
}
}
]
}));

server.setRequestHandler("tools/call", async (request) => {
if (request.params.name === "greet") {
const name = request.params.arguments.name;
return {
content: [{ type: "text", text: `안녕하세요, ${name}님!` }
};
}
throw new Error("Unknown tool");
});

const transport = new StdioServerTransport();
await server.connect(transport);

설정에 추가:

{
"mcpServers": {
"my-tool": {
"command": "npx",
"args": ["tsx", "path/to/my-server.ts"]
}
}
}

실전 예: 사내 API 연동

사내 REST API에 접근하는 MCP 서버를 구현하는 예입니다.

MCP 서버 구현 예 (사내 고객 API)

// .claude/mcp-servers/company-api.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const API_BASE = process.env.COMPANY_API_BASE_URL;
const API_KEY = process.env.COMPANY_API_KEY;

const server = new Server(
{ name: "company-api", version: "1.0.0" },
{ capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => (
tools: [
{
name: "search_customers",
description: "키워드로 고객을 검색한다 (최대 10건)",
inputSchema: {
type: "object",
properties: {
keyword: { type: "string", description: "검색 키워드 (회사명·담당자명)" }
},
required: ["keyword"]
}
},
{
name: "get_customer_detail",
description: "고객 ID로 고객 상세 정보를 취득한다",
inputSchema: {
type: "object",
properties: {
customerId: { type: "string", description: "고객 ID" }
},
required: ["customerId"]
}
}
]
}));

server.setRequestHandler("tools/call", async (request) => {
const headers = {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
};
if (request.params.name === "search_customers") {
const { keyword } = request.params.arguments;
const res = await fetch(`${API_BASE}/customers?q=${encodeURIComponent(keyword)}&limit=10`, { headers });
const data = await res.json();
// 개인정보 마스킹 처리
const masked = data.customers.map((c: any) => ({
id: c.id,
companyName: c.companyName,
contactName: c.contactName,
// 전화번호·이메일은 마스킹
phone: c.phone?.replace(/.(?=.{4})/g, "*"),
}));
return { content: [{ type: "text", text: JSON.stringify(masked, null, 2) }] };
}
if (request.params.name === "get_customer_detail") {
const { customerId } = request.params.arguments;
const res = await fetch(`${API_BASE}/customers/${customerId}`, { headers });
const data = await res.json();
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
}

throw new Error("Unknown tool");
});

const transport = new StdioServerTransport();
await server.connect(transport);

설정

{
"mcpServers": {
"company-api": {
"command": "npx",
"args": ["tsx", ".claude/mcp-servers/company-api.ts"],
"env": {
"COMPANY_API_BASE_URL": "${COMPANY_API_BASE_URL}",
"COMPANY_API_KEY": "${COMPANY_API_KEY}"
}
}
}
}

CLAUDE.md에 사용 방침 기술

## 사내 API (company-api MCP)

- 고객 검색: `search_customers` 툴로 최대 10건 취득
- 고객 상세: `get_customer_detail` 툴로 단건 취득
- 고객 정보 업데이트: 금지. 조회 전용
- 취득한 고객 정보를 로그나 파일에 기록하지 않는다
- 대량 조회(100건 이상)는 사용자 확인 후 실행

보안 설계

MCP 서버는 외부 서비스에 대한 실제 접근 권한을 갖기 때문에, 보안 설계가 특히 중요합니다.

인증 정보 관리

# .env (Git 제외)
DATABASE_URL=postgresql://readonly_user:password@localhost:5432/devdb
GITHUB_TOKEN=ghp_...
SLACK_BOT_TOKEN=xoxb-...
COMPANY_API_KEY=...

// .claude/settings.json (Git 포함 가능)
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
}
}
}