05. MCP

윤성진·약 23시간 전

Claude Code 빠르게 마스터 하기

목록 보기

6/6

https://wikidocs.net/book/19664

위 내용을 정리한 것이다.

MCP는 Claude Code가 외부 도구, API, 실시간 데이터에 접근하기 위한 표준 프로토콜이다.
메모리는 변하지 않는 컨텍스트를, MCP는 매번 변하는 외부 시스템을 다룬다.
Github, Slack, 데이터베이스 같은 외부 서비스에 Claude가 직접 접근하게 하고 싶을 때 사용한다.
실시간으로 변하는 데이터(이슈, PR, 모니터링 지표)를 대화 중 조회하고 싶을 때 사용한다.
사내 API나 자체 서비스를 Claude가 도구로 쓸 수 있게 노출하고 싶을 때 사용한다.
GitHub MCP 하나를 가장 빠르게 등록할 수 있다.

claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

05-01. 개요

MCP는 Claude가 외부 도구, API 및 실시간 데이터 소스에 접근하기 위한 표준화된 방법이다.
주요 특성은 다음과 같다:
- 외부 서비스에 대한 실시간 접근
- 실시간 데이터 동기화
- 확장 가능한 아키텍처
- 안전한 인증
- 도구 기반 상호작용

05-02. MCP 아키텍처

!image.png

05-03. MCP 생태계

05-04. MCP 설치 방법

Claude Code는 MCP 서버 연결을 위해 여러 전송 프로토콜을 지원한다:

HTTP 전송. 가장 권장되는 방법이다.

# Basic HTTP connection
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP with authentication header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

로컬에서 진행되는 MCP 서버의 경우 Stdio 전송을 사용한다.

# Local Node.js server
claude mcp add --transport stdio myserver -- npx @myorg/mcp-server

# With environment variables
claude mcp add --transport stdio myserver --env KEY=value -- npx server

--scope 플래그를 사용하여 MCP 구성이 저장되는 위치를 지정할 수 있다,

# Local 범위 (기본값) - 현재 프로젝트, 현재 사용자 전용
claude mcp add --transport http github https://api.github.com/mcp

# 명시적으로 local scope 지정
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# User 범위 - 모든 프로젝트에서 사용 가능
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

# Project 범위 - .mcp.json에 저장, 팀과 공유 가능
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

05-05. 설치 안내

MCP를 처음 도입할 때의 절차를 기술한다. 다음과 같은 전제가 필요하다.
- Node.js 및 npm 설치
- Claude Code CLI 설치
- 외부 서비스를 위한 API 토큰/자격 증명
다음과 같은 절차를 따른다:
1. 첫 번째 MCP 서버 추가 CLI를 사용한다.
  
  bash claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github
  
  또는 프로젝트 루트에 .msp.json 파일을 생성한다.
  
  json { "mcpServers": { "github": { "command": "npx", "args": ["@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } } } }
2. 환경 변수 설정
  
  bash export GITHUB_TOKEN="your_github_personal_access_token”
3. 연결 테스트
  
  bash claude /mcp
4. MCP 도구 사용
  
  bash /mcp__github__list_prs /mcp__github__create_issue "Title" "Description”

npm install -g @modelcontextprotocol/server-github

npm install -g @modelcontextprotocol/server-database

npm install -g @modelcontextprotocol/server-filesystem

npm install -g @modelcontextprotocol/server-slack

05-06. MCP 설정 프로세스

!image.png

05-07. MCP 구성 관리

# Add HTTP-based server
claude mcp add --transport http github https://api.github.com/mcp

# Add local stdio server
claude mcp add --transport stdio database -- npx @company/db-server

# List all MCP servers
claude mcp list

# Get details on specific server
claude mcp get github

# Remove an MCP server
claude mcp remove github

# Reset project-specific approval choices
claude mcp reset-project-choices

# Import from Claude Desktop
claude mcp add-from-claude-desktop

MCP 범위

범위	위치	설명	공유 대상	승인 필요
Local (기본값)	`~/.claude.json` (프로젝트 경로 아래)	현재 사용자, 현재 프로젝트 전용 (이전 버전에서는 `project`로 불림)	본인만	아니오
Project	`.mcp.json`	git 저장소에 체크인됨	팀원	예 (최초 사용 시)
User	`~/.claude.json`	모든 프로젝트에서 사용 가능 (이전 버전에서는 `global`로 불림)	본인만	아니오

프로젝트별 MCP 구성을 .mcp.json에 저장할 수 있다.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp"
    }
  }
}

05-09. 서버 중복 제거

동일한 MCP 서버가 여러 범위에서 정의되면 로컬 설정이 우선한다.

05-10. OAuth 2.0 인증

Claude Code는 OAuth 2.0을 요구하는 MCP 서버를 지원한다. OAuth가 활서오하된 서버에 연결할 때 Claude Code가 전체 인증 흐름을 처리한다.

# Connect to an OAuth-enabled MCP server (interactive flow)
claude mcp add --transport http my-service https://my-service.example.com/mcp

# Pre-configure OAuth credentials for non-interactive setup
claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --callback-port 8080

기능	설명
Interactive OAuth	`/mcp`를 사용하여 브라우저 기반 OAuth 흐름을 트리거합니다
Pre-configured OAuth clients	Notion, Stripe 등 일반적인 서비스를 위한 내장 OAuth 클라이언트 (v2.1.30+)
Pre-configured credentials	자동화된 설정을 위한 `--client-id`, `--client-secret`, `--callback-port` 플래그
Token storage	토큰은 시스템 키체인에 안전하게 저장됩니다
Step-up auth	권한이 필요한 작업에 대한 단계적 인증을 지원합니다
Discovery caching	빠른 재연결을 위해 OAuth 디스커버리 메타데이터가 캐시됩니다
Metadata override	기본 OAuth 메타데이터 디스커버리를 재정의하기 위한 `.mcp.json`의 `oauth.authServerMetadataUrl`

MCP 서버가 표준 OAuth 메타데이터 엔드포인트(./well-known/oauth-authorization-server)에서 오류를 반환하지만 작동하는 OIDC 엔드포인트를 제공하는 경우, Claude Code에 특정 URL에서 OAuth 메타데이터를 가져오도록 지시할 수 있다.
서버 설정의 oauth 객체에서 authServerMetadataURL을 설정한다. URL은 반드시 https://를 사용해야 한다:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

예측 가능한 로컬 redirect target이 필요하다면 설정 시 --callback-port를 명시한다:

claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --callback-port 8080

다음 상황에서 특히 유용하다:
- 로컬 firewall이 특정 loopback port만 허용하는 경우
- 팀용 setup instruction을 반복 가능하게 만들고 싶은 경우
- random ephemeral port보다 고정 포트가 브라우저 redirect troubleshooting에 유리한 경우
비대화식 또는 반자동 setup에서는 OAuth client identity를 미리 넣을 수 있다:

claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --callback-port 8080

다음 상황에 적합하다:
- 팀에서 이미 OAuth client를 provision해 둔 경우
- manual client creation 없이 따라 할 수 있는 setup 문서가 필요한 경우
- CI나 scripted bootstrap flow에서 안정적인 client metadata가 필요한 경우
OAuth만으로 끝나지 않는 HTTP MCP 서버는 추가 인증 헤더가 필요할 수 있다.
이때는 secret을 하드코딩하지 말고 environment-backed configuaration으로 header를 동적으로 넣는 것이 좋다.
실무 패턴은 다음과 같다:
- 민감한 값은 environment variable에 저장.
- sever configuration 또는 wrapper script에서 참조.
- header 생성 로직은 connection definition 가까이에 둬서 audit 가능하게 유지.
OAuth를 쓸 수 있다면 OAuth를 우선하고, 서비스 특성상 꼭 필요할 때만 custon header를 추가하는 것이 좋다.

05-11. 환경 변수

MCP 설정에서 자격 증명을 다룰 때 환경 변수에 저장하고 ${VAR}로 참조하는 표준 패턴을 정리한다.
민감한 자격 증명을 환경 변수에 저장한다.

# ~/.bashrc or ~/.zshrc
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="xoxb-xxxxxxxxxxxxx"

그런 다음 MCP 설정에서 참조한다.

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

05-12. @ 멘션을 통한 MCP 리소스

@server-name:protocol://resource/path 형식으로 MCP 리소스를 인라인 컨텍스트로 끌어오는 방법을 기술한다.
- 도구 호출까지 가지 않고 단순 데이터를 prompt 안에 즉시 끼워 넣고 싶을 때 가장 빠른 방법이다.
@ 멘션 구문을 사용하여 프롬프트에서 MCP 리소스를 직접 참조할 수 있다.

@server-name:protocol://resource/path

특정 데이터베이스 리소스를 참조하려면 다음과 같이 작성한다.

@database:postgres://mydb/users

05-13. MCP Tool Search

도구 설명이 컨텍스트 윈도우의 10%를 넘으면 자동으로 켜지는 Tool Search 기능을 정리한다.
- 큰 MCP surface를 운영하는 팀이나 MCP 서버를 직접 만드는 사람이 우선 봐야 할 페이지이다.
- 각 MCP 서버의 도구 설명은 2KB로 제한된다. 이 제한을 초과하는 설명은 잘린다.

설정	값	설명
`ENABLE_TOOL_SEARCH`	`auto` (기본값)	도구 설명이 컨텍스트의 10%를 초과하면 자동 활성화
`ENABLE_TOOL_SEARCH`	`auto:<N>`	커스텀 임계값 `N`개 도구에서 자동 활성화
`ENABLE_TOOL_SEARCH`	`true`	도구 수에 관계없이 항상 활성화
`ENABLE_TOOL_SEARCH`	`false`	비활성화; 모든 도구 설명이 전체로 전송됨

Tool Search는 모든 도구 설명을 한 번에 컨텍스트에 넣지 않고, 필요한 도구를 먼저 좁히는 방식으로 동작한다.
개념적으로는 다음 절차를 따른다:
1. Claude가 MCP 서버 집합을 확인
2. Tool Search로 후보 도구를 좁힘
3. 관련 도구 설명만 더 자세히 surface
이 덕분에 큰 MCP 설치에서도 매 turn마다 모든 도구 설명 비용을 내지 않아도 된다.
핵심 장점은 “큰 도구 상자를 유지하면서도 컨텍스트 폭증을 막는 것”이다.
핵심 제어면은 ENABLE_TOOL_SEARCH이다:
- auto는 기본 적응형 동작 유지
- auto:<N>은 임계값을 조정
- true는 항상 활성화
- false는 비활성화하고 모든 도구 설명을 그대로 보냄
실무 기준은 다음과 같다:
- 일반 프로젝트는 auto
- MCP surface가 크고 안정적이면 true
- debugging이나 전체 설명을 일부러 보고 싶을 때만 false
MCP 서버를 직접 배포하거나 유지한다면 Tool Search가 켜진 환경에서도 잘 동작하도록 도구를 설계해야 한다. 좋은 규칙은 다음과 같다:
- tool name은 서로 명확히 구분되게 짓기
- description은 짧고 앞부분이 강하게 읽히게 쓰기
- tool description 안에 거대한 instruction block을 넣지 않기
- truncation이 걸려도 첫 문장만으로 용도를 알 수 있게 만들기
Tool Search는 이름과 한 줄 설명만으로도 도구를 구분할 수 있을 때 가장 잘 작동한다.

05-14. MCP 출력 제한

Claude Code는 컨텍스트 오버플로우를 방지하기 위해 MCP 도구 출력에 제한을 적용한다:

제한	임계값	동작
경고	10,000 토큰	출력이 크다는 경고가 표시됩니다
기본 최대값	25,000 토큰	이 한도를 초과하면 출력이 잘립니다
디스크 저장	50,000 문자	50K 문자를 초과하는 도구 결과는 디스크에 저장됩니다

최대 출력 제한은 MAX_MCP_OUTPUT_TOKENS 환경 변수를 통해 구성할 수 있다.

# Increase the max output to 50,000 tokens
export MAX_MCP_OUTPUT_TOKENS=50000

Claude Code의 주요 CLI surface에는 per-tool 전용 cap보다 MAX_MCP_OUTPUT_TOKENS라는 global cap이 먼저 노출된다.
실무 기준은 다음과 같다:
- 전체 한도를 올려야 할 때만 MAX_MCP_OUTPUT_TOKENS 사용
- 특정 도구 하나만 noisy하다면 server-side에서 출력 자체를 shaping
- 가능하면 global cap 상향보다 paging, filtering, summarization을 우선
  - 문제가 되는 것이 한 도구라면, 전체 한도를 올리기 전에 그 도구의 output contract를 먼저 손보는 것이 낫다.
Channels와 MCP는 가까운 개념이지만 역할은 다르다. channels는 MCP-backed eventn stream이고, 일반 MCP tool은 request/response 도구이다.
일반 MCP tool을 사용하는 것이 옳은 경우:
- Claude가 필요할 때 데이터를 요청
- 상호작용이 request/response 구조
Channels를 사용하는 것이 옳은 경우:
- 외부 시스템이 live session으로 이벤트를 push
- Claude가 alert, chat message, webhook 기반 상태 변화에 반응해야 함
즉 channels는 event ingress를, 일반 MCP tool은 data/action access를 해결한다.

05-15. 동적 도구 업데이트

Claude Code는 MCP list_changed 알림을 지원한다.
MCP 서버가 사용 가능한 도구를 동적으로 추가, 제거 또는 수정하면, Claude Code가 업데이트를 수신하고 도구 목록을 자동으로 조정한다.
- 재연결이나 재시작이 필요 없다.

05-16. 도구 설명 및 지시 제한

Claude Code는 MCP 서버당 도구 설명과 지시에 2KB 제한을 적용한다.
- 이는 개별 서버가 지나치게 장황한 도구 정의로 과도한 컨텍스트를 소비하는 것을 방지하여, 컨텍스트 팽창을 줄이고 상호작용을 효율적으로 유지한다.

05-17. 코드 실행으로 컨텍스트 팽창 해결

MCP 채택이 확대됨에 따라, 많은 서버 및 도구에 연결하면 컨텍스트 팽창이 발생한다.
- 직접 도구 호출 대신 코드 실행을 이용하는 것으로 이 문제를 해결할 수 있다.
토큰을 낭비하는 데에는 두 가지 요인이 있다:
1. 도구 정의가 컨텍스트 윈도우를 과부하함
  
  대부분의 MCP 클라이언트는 모든 도구 정의를 사전에 로드한다. 수천 개의 도구에 연결되면, 모델은 사용자의 요청을 읽기도 전에 수십만 토큰을 처리해야 한다.
2. 중간 결과가 추가 토큰을 소비함
  
  모든 중간 도구 결과가 모델의 컨텍스트를 통과한다.

!image.png

MCP 도구를 코드 API로 대체하는 것으로 문제를 해결할 수 있다.

!image.png

MCP 도구는 타입이 지정된 함수의 파일 트리로 제공된다:

servers/
├── google-drive/
│   ├── getDocument.ts
│   └── index.ts
├── salesforce/
│   ├── updateRecord.ts
│   └── index.ts
└── ...

각 도구 파일에는 타입이 지정된 래퍼가 포함된다:

// ./servers/google-drive/getDocument.ts
import { callMCPTool } from "../../../client.js";

interface GetDocumentInput {
  documentId: string;
}

interface GetDocumentResponse {
  content: string;
}

export async function getDocument(
  input: GetDocumentInput
): Promise<GetDocumentResponse> {
  return callMCPTool<GetDocumentResponse>(
    'google_drive__get_document', input
  );
}

그런 다음 agent가 도구를 조율하는 코드를 작성한다:

import * as gdrive from './servers/google-drive';
import * as salesforce from './servers/salesforce';

// Data flows directly between tools — never through the model
const transcript = (
  await gdrive.getDocument({ documentId: 'abc123' })
).content;

await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  recordId: '00Q5f000001abcXYZ',
  data: { Notes: transcript }
});

이점	설명
Progressive Disclosure	Agent가 모든 도구를 사전에 로드하는 대신, 필요한 도구 정의만 파일시스템을 탐색하여 로드합니다
Context-Efficient Results	모델에 반환되기 전에 실행 환경에서 데이터가 필터링/변환됩니다
Powerful Control Flow	루프, 조건문, 오류 처리가 모델을 거치지 않고 코드에서 실행됩니다
Privacy Preservation	중간 데이터(PII, 민감한 레코드)가 실행 환경에 머물며 모델 컨텍스트에 들어가지 않습니다
State Persistence	Agent가 중간 결과를 파일로 저장하고 재사용 가능한 skill 함수를 구축할 수 있습니다

코드 실행은 자체적인 복잡성을 도입한다. agent가 생성한 코드를 실행하려면 다음이 필요하다:
- 적절한 리소스 제한이 있는 안전한 샌드박스 실행 환경
- 실행된 코드의 모니터링 및 로깅
- 직접 도구 호출에 비해 추가적인 인프라 오버헤드
소수의 MCP 서버만 있는 agent의 경우, 직접 도구 호출이 더 간단할 수 있다. 대규모 agent의 경우, 코드 실행은 상당한 개선이다.
MCPorter는 보일러플레이트 없이 MCP 서버 호출을 실용적으로 만드는 TypeScript 런타임 및 CLI 도구 키드이다. 선택적 도구 노출과 타입이 지정된 래퍼를 통해 컨텍스트 팽창을 줄이는 데 도움을 준다.
- 모든 MCP 서버의 모든 도구 정의를 사전에 로드하는 대신, MCPorter를 사용하면 특정 도구를 요청 시 검색, 검사 및 호출할 수 있어 컨텍스트를 가볍게 유지한다.

기능	설명
Zero-config discovery	Cursor, Claude, Codex 또는 로컬 설정에서 MCP 서버를 자동 검색합니다
Typed tool clients	`mcporter emit-ts`가 `.d.ts` 인터페이스와 바로 실행 가능한 래퍼를 생성합니다
Composable API	`createServerProxy()`가 `.text()`, `.json()`, `.markdown()` 헬퍼와 함께 camelCase 메서드로 도구를 노출합니다
CLI generation	`mcporter generate-cli`가 MCP 서버를 `--include-tools` / `--exclude-tools` 필터링이 있는 독립형 CLI로 변환합니다
Parameter hiding	선택적 매개변수가 기본적으로 숨겨져 스키마 장황함을 줄입니다

설치는 다음 명령어로 진행한다.

npx mcporter list          # No install required — discover servers instantly
pnpm add mcporter          # Add to a project
brew install steipete/tap/mcporter  # macOS via Homebrew

TypeScript에서의 도구 구성은 다음과 같다:

import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();
const gdrive = createServerProxy(runtime, "google-drive");
const salesforce = createServerProxy(runtime, "salesforce");

// Data flows between tools without passing through the model context
const doc = await gdrive.getDocument({ documentId: "abc123" });
await salesforce.updateRecord({
  objectType: "SalesMeeting",
  recordId: "00Q5f000001abcXYZ",
  data: { Notes: doc.text() }
});

CLI 도구 호출은 다음과 같다:

# Call a specific tool directly
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

# List available servers and tools
npx mcporter list

MCPorter는 위에서 설명한 코드 실행 접근 방식을 보완하여 MCP 도구를 타입이 지정된 API로 호출하기 위한 런타임 인프라를 제공한다. 중간 데이터를 모델 컨텍스트에서 벗어나게 유지하는 것을 간단하게 만든다.

05-18. MCP Apps

MCP Apps는 MCP 도구 호출이 채팅 인터페이스에 직접 렌더링되는 대화형 UI 컴포넌트를 반환할 수 있게 하는 확장 기능이다.
일반 텍스트 응답 대신, MCP 서버가 풍부한 대시보드, 양식, 데이터 시각화 및 다단계 워크플로우를 전달할 수 있으며, 모두 대화를 벗어나지 않고 인라인으로 표시된다.

05-19. MCP Elicitation

MCP 서버는 대화형 대화 상자를 통해 사용자로부터 구조화된 입력을 요청할 수 있다.
이를 통해 MCP 서버가 워크플로우 도중에 추가 정보를 요청할 수 있다.
- 확인을 요청하거나, 옵션 목록에서 선택하거나, 필수 필드를 채우는 등.
MCP 서버 상호작용에 대화형 기능을 추가한다.
Elicitation은 자유 형식 prompt라기보다는 반구조화 form exchange처럼 다루는 것이 좋다.
기준은 다음과 같다:
- 서버가 정확히 무엇을 요청하는지 먼저 검증
- 필요한 필드를 명확히 유지
- 이후 로그를 남길 경우 민감한 응답은 정규화하거나 redaction
MCP 서버가 multi-step workflow와 human input checkpoint를 섞어 쓰는 경우, 이 지점에서 hook 기반 validation도 특히 유용하다.
Elicitation 및 ElicitationResult hook 이벤트를 통해 elicitation 요청에 프로그래밍 방식으로 자동 응답하거나, 사용자 응답을 서버로 보내기 전에 가로채서 수정할 수 있다.

05-20. MCP Prompts를 Slash Commands로

MCP 서버는 Claude Code에서 slash command로 나타나는 프롬프트를 노출할 수 있다.
프롬프트는 다음 명명 규칙을 사용하여 접근할 수 있다:

/mcp__<server>__<prompt>

05-21. Plugin 제공 MCP 서버

Plugin은 자체 MCP 서버를 번들할 수 있어, plugin이 설치되면 자동으로 사용 가능하다.
Plugin 제공 MCP 서버는 두 가지 방법으로 정의할 수 있다:
1. 독립형. .mcp.json —plugin 루트 디렉토리에 .mcp.json 파일 배치
2. plugin.json 내 인라인 —plugin 매니페스트 내에서 직접 MCP 서버 정의
plugin의 설치 디렉토리에 상대적인 경로를 참조하기 위해 ${CLAUDE_PLUGIN_ROOT} 변수를 사용한다:

{
  "mcpServers": {
    "plugin-tools": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"],
      "env": {
        "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json"
      }
    }
  }
}

05-22. Subagent 범위 MCP

MCP 서버는 mcpServers: 키를 사용하여 agent frontmatter 내에서 인라인으로 정의할 수 있으며, 전체 프로젝트가 아닌 특정 subagent로 범위를 제한한다.
이는 워크플로우의 다른 agent가 필요로 하지 않는 특정 MCP 서버에 agent가 접근해야 할 때 유용하다.

---
mcpServers:
  my-tool:
    type: http
    url: https://my-tool.example.com/mcp
---

You are an agent with access to my-tool for specialized operations.

Subagent 범위 MCP 서버는 해당 agent의 실행 컨텍스트 내에서만 사용 가능하며 부모나 형제 agent와 공유되지 않는다.

05-23. Claude를 MCP 서버로 (`claude mcp serve`)

Claude Code 자체가 다른 애플리케이션을 위한 MCP 서버로 동작할 수 있다.
이를 통해 외부 도구, 편집기 및 자동화 시스템이 표준 MCP 프로토콜을 통해 Claude의 기능을 활용할 수 있다.

# Start Claude Code as an MCP server on stdio
claude mcp serve

다른 애플리케이션은 일반 stdio 기반 MCP 서버처럼 이 서버에 연결할 수 있다.
가령 다른 Claude Code 인스턴스에서 Claude Code를 MCP 서버로 추가하려면:

claude mcp add --transport stdio claude-agent -- claude mcp serve

이는 하나의 Claude 인스턴스가 다른 인스턴스를 조율하는 다중 agent 워크플로우를 구축하는 데 유용하다.

05-24. 요청/응답 패턴

!image.png

05-25. 사용 가능한 MCP 서버 테이블

MCP 서버	용도	주요 도구	인증	실시간
Filesystem	파일 작업	read, write, delete	OS 권한	예
GitHub	저장소 관리	list_prs, create_issue, push	OAuth	예
Slack	팀 커뮤니케이션	send_message, list_channels	토큰	예
Database	SQL 쿼리	query, insert, update	자격 증명	예
Google Docs	문서 접근	read, write, share	OAuth	예
Asana	프로젝트 관리	create_task, update_status	API 키	예
Stripe	결제 데이터	list_charges, create_invoice	API 키	예
Memory	영구 메모리	store, retrieve, delete	로컬	아니오

05-26. 실용 예제

처음 MCP를 도입할 때 “코드로 어떻게 쓰는가”를 보고 싶을 때 본다.
${VAR}/${VAR:-default} 환경변수 확장 같은 공통 문법도 기술한다.
GitHub MCP 구성

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

사용 가능한 GitHub MCP 도구는 다음과 같다:
- Pull Request 관리
  - list_prs - 저장소의 모든 PR 나열
  - get_pr - diff를 포함한 PR 세부 정보 가져오기
  - create_pr- 새 PR 생성
  - update_pr - PR 설명/제목 업데이트
  - merge_pr - PR을 메인 브랜치에 병합
  - review_pr - 리뷰 코멘트 추가
  - 요청 예시는 다음과 같다.
```
/mcp__github__get_pr 456

# Returns:
Title: Add dark mode support
Author: @alice
Description: Implements dark theme using CSS variables
Status: OPEN
Reviewers: @bob, @charlie
```
- 이슈 관리
  - list_issues - 모든 이슈 나열
  - get_issue - 이슈 세부 정보 가져오기
  - create_issue - 새 이슈 생성
  - close_issue - 이슈 닫기
  - add_comment - 이슈에 코멘트 추가
- 저장소 정보
  - get_repo_info - 저장소 세부 정보
  - list_files - 파일 트리 구조
  - get_file_content - 파일 내용 읽기
  - search_code - 코드베이스 전체 검색
- 커밋 작업
  - list_commits - 커밋 히스토리
  - get_commit - 특정 커밋 세부 정보
  - create_commit - 새 커밋 생성
```
export GITHUB_TOKEN="your_github_token"
# Or use the CLI to add directly:
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github
```
MCP 구성은 대체 기본값이 있는 환경 변수 확장을 지원한다. ${VAR} 및 ${VAR:-default} 구문은 다음 필드에서 작동한다: command, args, env, url, headers.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}",
        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
      }
    },
    "local-server": {
      "command": "${MCP_BIN_PATH:-npx}",
      "args": ["${MCP_PACKAGE:-@company/mcp-server}"],
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}

변수는 런타임에 확장된다:
- ${VAR} - 환경 변수 사용, 설정되지 않으면 오류 - ${VAR:-default} - 환경 변수 사용, 설정되지 않으면 기본값으로 대체
Database MCP를 다음과 같이 설정할 수도 있다:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}

다음과 같이 사용할 수 있다:

User: Fetch all users with more than 10 orders

Claude: I'll query your database to find that information.

# Using MCP database tool:
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id
HAVING COUNT(o.id) > 10
ORDER BY order_count DESC;

# Results:
- Alice: 15 orders
- Bob: 12 orders
- Charlie: 11 orders

다음과 같이 설정한다:

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
# Or use the CLI to add directly:
claude mcp add --transport stdio database -- npx @modelcontextprotocol/server-database

다중 MCP 워크플로우 - 일일 보고서 작성도 가능하다.

# Daily Report Workflow using Multiple MCPs

## Setup
1. GitHub MCP - fetch PR metrics
2. Database MCP - query sales data
3. Slack MCP - post report
4. Filesystem MCP - save report

## Workflow

### Step 1: Fetch GitHub Data
/mcp__github__list_prs completed:true last:7days

Output:
- Total PRs: 42
- Average merge time: 2.3 hours
- Review turnaround: 1.1 hours

### Step 2: Query Database
SELECT COUNT(*) as sales, SUM(amount) as revenue
FROM orders
WHERE created_at > NOW() - INTERVAL '1 day'

Output:
- Sales: 247
- Revenue: $12,450

### Step 3: Generate Report
Combine data into HTML report

### Step 4: Save to Filesystem
Write report.html to /reports/

### Step 5: Post to Slack
Send summary to #daily-reports channel

Final Output:
Report generated and posted
47 PRs merged this week
$12,450 in daily sales

다음과 같이 설정한다.

export GITHUB_TOKEN="your_github_token"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="your_slack_token"
# Add each MCP server via the CLI or configure them in .mcp.json

Filesystem MCP 또한 가능하다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

작업	명령	용도
List files	`ls ~/projects`	디렉토리 내용 표시
Read file	`cat src/main.ts`	파일 내용 읽기
Write file	`create docs/api.md`	새 파일 생성
Edit file	`edit src/app.ts`	파일 수정
Search	`grep "async function"`	파일에서 검색
Delete	`rm old-file.js`	파일 삭제

다음과 같이 설정한다:

# Use the CLI to add directly:
claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects

05-27. 사례: WikiDocs MCP

위키독스 플랫폼이 자체 MCP 서버를 제공해 Claude Code, Claude Desktop, Cursor, Codex 같은 MCP 지원 도구에서 위키독스 책과 페이지를 직접 조회, 작성, 수정할 수 있다.
총 14개 도구를 제공한다.

영역	대표 도구	용도
책 관리	`list_books`, `create_book`, `get_book`, `get_book_toc`	내 책 목록·생성·구조 조회
페이지 관리	`create_page`, `get_page`, `update_page`, `upload_page_image`	페이지 단위 작성·수정·이미지 업로드
블로그 관리	`list_blogs`, `create_blog`, `update_blog`, `upload_blog_image` 외	위키독스 블로그 자동 발행

다음과 같은 명령어로 Claude Code에 등록할 수 있다.

claude mcp add --transport http wikidocs https://wikidocs.net/mcp \
  --header "Authorization: Token <발급받은 토큰>"

큰 책에서 무턱대고 get_book을 부르면 응답이 매우 커진다. 위키독스 가이드는 다음 흐름을 권한다:
1. get_book_toc로 구조부터 파악
2. 필요한 페이지 ID만 골라 get_page로 조회
3. update_page는 부분 수정 방식이므로 변경할 필드만 보낸다.
MCP 서버가 무엇을 반환하든 한 번에 다 받지 말고 토큰 단위로 끊어서 가져오는 것이 정석이다.

05-28. MCP vs Memory: 결정 매트릭스

!image.png

05-29. 관리형 MCP 구성 (기업용)

사용자나 프로젝트 설정보다 위에서 동작하는 게이트라 기업 배포, 보안 감사 시의 내용을 기술한다.
기업 배포의 경우, IT 관리자는 managed-mcp.json 구성 파일을 통해 MCP 서버 정책을 적용할 수 있다.
- 이 파일은 조직 전체에서 허용되거나 차단되는 MCP 서버에 대한 독점적 제어를 제공한다.
위치:
- macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
- Linux: ~/.config/ClaudeCode/managed-mcp.json
- Windows: %APPDATA%\ClaudeCode\managed-mcp.json
기능:
- allowedMcpServers -- 허용된 서버의 화이트리스트
- deniedMcpServers -- 금지된 서버의 블랙리스트
- 서버 이름, 명령 및 URL 패턴별 매칭 지원
- 사용자 구성 전에 적용되는 조직 전체 MCP 정책
- 비인가 서버 연결 방지
다음과 같이 구성할 수 있다. allowedMcpServers와 deniedMcpServers가 모두 서버와 매칭될 경우, 거부 규칙이 우선한다.

{
  "allowedMcpServers": [
    {
      "serverName": "github",
      "serverUrl": "https://api.github.com/mcp"
    },
    {
      "serverName": "company-internal",
      "serverCommand": "company-mcp-server"
    }
  ],
  "deniedMcpServers": [
    {
      "serverName": "untrusted-*"
    },
    {
      "serverUrl": "http://*"
    }
  ]
}

관리형 MCP policy는 일반 user/project configuration 앞에서 동작하는 gate라고 생각하면 된다:
- user/project config는 “무엇을 쓰고 싶은지”
- managed MCP policy는 “실제로 무엇이 허용되는지”
  - 정책이 서버를 막으면 더 낮은 scope가 그 결정을 뒤집을 수 없다.
명령 기반 제한은 local stdio 서버에 가장 유용하다. 다음과 같이 사용할 수 있다:
- 감사된 launcher command만 허용
- 안전하지 않은 wrapper script 차단
- package-manager 기반 launcher 패턴 제한
  - 팀이 특정 로컬 MCP binary에 의존한다면, 정확한 command form을 문서화하고 allowlist도 그 형태에 맞춰 두는 것이 중요하다.
URL 기반 제한은 remote HTTP, SSE, WebSocket MCP 서버에 가장 유용하다:
- 승인된 hostname만 허용
- insecure transport 차단
- 내부 도메인으로 사용 범위 제한
  - 이 레이어는 팀원이 승인된 MCP endpoint에만 연결하도록 강제하는 데 가장 적합하다.
정책 해석 규칙은 다음처럼 해석한다:
- allowlist만 있으면 그 밖의 서버는 사실상 제외
- denylist가 매칭되면 거부가 우선
- 둘 다 같은 서버에 매칭되면 차단된 것으로 처리
  - 운영 문서에는 실제 match example을 함께 남겨 두는 것이 좋다.

05-30. 모범 사례

보안 관련 권장 사항
- 모든 자격 증명에 환경 변수 사용
- 토큰과 API 키를 정기적으로 교체 (월 1회 권장)
- 가능하면 읽기 전용 토큰 사용
- MCP 서버 접근 범위를 최소한으로 제한
- MCP 서버 사용량 및 접근 로그 모니터링
- 외부 서비스에는 가능하면 OAuth 사용
- MCP 요청에 속도 제한 구현
- 프로덕션 사용 전에 MCP 연결 테스트
- 모든 활성 MCP 연결 문서화
- MCP 서버 패키지 업데이트 유지
비권장 사항
- 구성 파일에 자격 증명 하드코딩 금지
- 토큰이나 시크릿을 git에 커밋 금지
- 팀 채팅이나 이메일로 토큰 공유 금지
- 팀 프로젝트에 개인 토큰 사용 금지
- 불필요한 권한 부여 금지
- 인증 오류 무시 금지
- MCP 엔드포인트를 공개적으로 노출 금지
- root/admin 권한으로 MCP 서버 실행 금지
- 로그에 민감한 데이터 캐시 금지
- 인증 메커니즘 비활성화 금지
구성 모범 사례
1. 버전 관리. .mcp.json을 git에 유지하되 시크릿에는 환경 변수 사용
2. 최소 권한. 각 MCP 서버에 필요한 최소 권한 부여
3. 격리. 가능하면 서로 다른 MCP 서버를 별도의 프로세스에서 실행
4. 모니터링. 감사 추적을 위해 모든 MCP 요청과 오류 기록
5. 테스트. 프로덕션에 배포하기 전에 모든 MCP 구성 테스트
성능
- 자주 접근하는 데이터를 애플리케이션 레벨에서 캐시
- 데이터 전송을 줄이기 위해 구체적인 MCP 쿼리 사용
- MCP 작업의 응답 시간 모니터링
- 외부 API에 대한 속도 제한 고려
- 여러 작업 수행 시 배치 사용

05-31. 문제 해결

MCP 서버를 찾을 수 없는 경우:

# Verify MCP server is installed
npm list -g @modelcontextprotocol/server-github

# Install if missing
npm install -g @modelcontextprotocol/server-github

인증 실패:

# Verify environment variable is set
echo $GITHUB_TOKEN

# Re-export if needed
export GITHUB_TOKEN="your_token"

# Verify token has correct permissions
# Check GitHub token scopes at: https://github.com/settings/tokens

연결 시간 초과:
- 네트워크 연결 확인: ping api.github.com
- API 엔드포인트 접근 가능 여부 확인
- API의 속도 제한 확인
- 설정에서 시간 초과 값 증가 시도
- 방화벽 또는 프록시 문제 확인
MCP 서버 충돌:
- MCP 서버 로그 확인: ~/.claude/logs/
- 모든 환경 변수가 설정되었는지 확인
- 적절한 파일 권한 보장
- MCP 서버 패키지 재설치 시도
- 동일 포트의 충돌하는 프로세스 확인

05-32. 관련 개념

Memory vs MCP
- Memory: 영구적이고 변하지 않는 데이터 저장 (선호사항, 컨텍스트, 히스토리)
- MCP: 실시간으로 변하는 데이터 접근 (API, 데이터베이스, 실시간 서비스)
사용 시점
- Memory: 사용자 선호사항, 대화 히스토리, 학습된 컨텍스트
- MCP 사용: 현재 GitHub 이슈, 실시간 데이터베이스 쿼리, 실시간 데이터
다른 Claude 기능과의 통합
- MCP와 Memory를 결합하여 풍부한 컨텍스트 제공
- 더 나은 추론을 위해 프롬프트에서 MCP 도구 사용
- 복잡한 워크플로우를 위해 여러 MCP 활용

윤성진

dev

이전 포스트

05. MCP

Claude Code 빠르게 마스터 하기

05-01. 개요

05-02. MCP 아키텍처

05-03. MCP 생태계

05-04. MCP 설치 방법

05-05. 설치 안내

05-06. MCP 설정 프로세스

05-07. MCP 구성 관리

MCP 범위

05-09. 서버 중복 제거

05-10. OAuth 2.0 인증

05-11. 환경 변수

05-12. @ 멘션을 통한 MCP 리소스

05-13. MCP Tool Search

05-14. MCP 출력 제한

05-15. 동적 도구 업데이트

05-16. 도구 설명 및 지시 제한

05-17. 코드 실행으로 컨텍스트 팽창 해결

05-18. MCP Apps

05-19. MCP Elicitation

05-20. MCP Prompts를 Slash Commands로

05-21. Plugin 제공 MCP 서버

05-22. Subagent 범위 MCP

05-23. Claude를 MCP 서버로 (`claude mcp serve`)

05-24. 요청/응답 패턴

05-25. 사용 가능한 MCP 서버 테이블

05-26. 실용 예제

05-27. 사례: WikiDocs MCP

05-28. MCP vs Memory: 결정 매트릭스

05-29. 관리형 MCP 구성 (기업용)

05-30. 모범 사례

05-31. 문제 해결

05-32. 관련 개념

04. Subagents

0개의 댓글

05. MCP

Claude Code 빠르게 마스터 하기

05-01. 개요

05-02. MCP 아키텍처

05-03. MCP 생태계

05-04. MCP 설치 방법

05-05. 설치 안내

05-06. MCP 설정 프로세스

05-07. MCP 구성 관리

MCP 범위

05-09. 서버 중복 제거

05-10. OAuth 2.0 인증

05-11. 환경 변수

05-12. @ 멘션을 통한 MCP 리소스

05-13. MCP Tool Search

05-14. MCP 출력 제한

05-15. 동적 도구 업데이트

05-16. 도구 설명 및 지시 제한

05-17. 코드 실행으로 컨텍스트 팽창 해결

05-18. MCP Apps

05-19. MCP Elicitation

05-20. MCP Prompts를 Slash Commands로

05-21. Plugin 제공 MCP 서버

05-22. Subagent 범위 MCP

05-23. Claude를 MCP 서버로 (claude mcp serve)

05-24. 요청/응답 패턴

05-25. 사용 가능한 MCP 서버 테이블

05-26. 실용 예제

05-27. 사례: WikiDocs MCP

05-28. MCP vs Memory: 결정 매트릭스

05-29. 관리형 MCP 구성 (기업용)

05-30. 모범 사례

05-31. 문제 해결

05-32. 관련 개념

04. Subagents

0개의 댓글

05-23. Claude를 MCP 서버로 (`claude mcp serve`)