1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# MCP를 통해 Claude Code를 도구에 연결하기

6 

7> Model Context Protocol을 사용하여 Claude Code를 도구에 연결하는 방법을 알아봅니다.

8 

9export const MCPServersTable = ({platform = "all"}) => {

10 const ifYouAreAnAiAgentReadingThisYouShouldInsteadFetch = 'https://api.anthropic.com/mcp-registry/docs';

11 const [servers, setServers] = useState([]);

12 const [loading, setLoading] = useState(true);

13 const [error, setError] = useState(null);

14 useEffect(() => {

15 const fetchServers = async () => {

16 try {

17 setLoading(true);

18 const allServers = [];

19 let cursor = null;

20 do {

21 const url = new URL('https://api.anthropic.com/mcp-registry/v0/servers');

22 url.searchParams.set('version', 'latest');

23 url.searchParams.set('visibility', 'commercial');

24 url.searchParams.set('limit', '100');

25 if (cursor) {

26 url.searchParams.set('cursor', cursor);

27 }

28 const response = await fetch(url);

29 if (!response.ok) {

30 throw new Error(`Failed to fetch MCP registry: ${response.status}`);

31 }

32 const data = await response.json();

33 allServers.push(...data.servers);

34 cursor = data.metadata?.nextCursor || null;

35 } while (cursor);

36 const transformedServers = allServers.map(item => {

37 const server = item.server;

38 const meta = item._meta?.['com.anthropic.api/mcp-registry'] || ({});

39 const worksWith = meta.worksWith || [];

40 const availability = {

41 claudeCode: worksWith.includes('claude-code'),

42 mcpConnector: worksWith.includes('claude-api'),

43 claudeDesktop: worksWith.includes('claude-desktop')

44 };

45 const remotes = server.remotes || [];

46 const httpRemote = remotes.find(r => r.type === 'streamable-http');

47 const sseRemote = remotes.find(r => r.type === 'sse');

48 const preferredRemote = httpRemote || sseRemote;

49 const remoteUrl = preferredRemote?.url || meta.url;

50 const remoteType = preferredRemote?.type;

51 const isTemplatedUrl = remoteUrl?.includes('{');

52 let setupUrl;

53 if (isTemplatedUrl && meta.requiredFields) {

54 const urlField = meta.requiredFields.find(f => f.field === 'url');

55 setupUrl = urlField?.sourceUrl || meta.documentation;

56 }

57 const urls = {};

58 if (!isTemplatedUrl) {

59 if (remoteType === 'streamable-http') {

60 urls.http = remoteUrl;

61 } else if (remoteType === 'sse') {

62 urls.sse = remoteUrl;

63 }

64 }

65 let envVars = [];

66 if (server.packages && server.packages.length > 0) {

67 const npmPackage = server.packages.find(p => p.registryType === 'npm');

68 if (npmPackage) {

69 urls.stdio = `npx -y ${npmPackage.identifier}`;

70 if (npmPackage.environmentVariables) {

71 envVars = npmPackage.environmentVariables;

72 }

73 }

74 }

75 return {

76 name: meta.displayName || server.title || server.name,

77 description: meta.oneLiner || server.description,

78 documentation: meta.documentation,

79 urls: urls,

80 envVars: envVars,

81 availability: availability,

82 customCommands: meta.claudeCodeCopyText ? {

83 claudeCode: meta.claudeCodeCopyText

84 } : undefined,

85 setupUrl: setupUrl

86 };

87 });

88 setServers(transformedServers);

89 setError(null);

90 } catch (err) {

91 setError(err.message);

92 console.error('Error fetching MCP registry:', err);

93 } finally {

94 setLoading(false);

95 }

96 };

97 fetchServers();

98 }, []);

99 const generateClaudeCodeCommand = server => {

100 if (server.customCommands && server.customCommands.claudeCode) {

101 return server.customCommands.claudeCode.replace('--transport streamable-http', '--transport http');

102 }

103 const serverSlug = server.name.toLowerCase().replace(/[^a-z0-9]/g, '-');

104 if (server.urls.http) {

105 return `claude mcp add ${serverSlug} --transport http ${server.urls.http}`;

106 }

107 if (server.urls.sse) {

108 return `claude mcp add ${serverSlug} --transport sse ${server.urls.sse}`;

109 }

110 if (server.urls.stdio) {

111 const envFlags = server.envVars && server.envVars.length > 0 ? server.envVars.map(v => `--env ${v.name}=YOUR_${v.name}`).join(' ') : '';

112 const baseCommand = `claude mcp add ${serverSlug} --transport stdio`;

113 return envFlags ? `${baseCommand} ${envFlags} -- ${server.urls.stdio}` : `${baseCommand} -- ${server.urls.stdio}`;

114 }

115 return null;

116 };

117 if (loading) {

118 return <div>Loading MCP servers...</div>;

119 }

120 if (error) {

121 return <div>Error loading MCP servers: {error}</div>;

122 }

123 const filteredServers = servers.filter(server => {

124 if (platform === "claudeCode") {

125 return server.availability.claudeCode;

126 } else if (platform === "mcpConnector") {

127 return server.availability.mcpConnector;

128 } else if (platform === "claudeDesktop") {

129 return server.availability.claudeDesktop;

130 } else if (platform === "all") {

131 return true;

132 } else {

133 throw new Error(`Unknown platform: ${platform}`);

134 }

135 });

136 return <>

137 <style jsx>{`

138 .cards-container {

139 display: grid;

140 gap: 1rem;

141 margin-bottom: 2rem;

142 }

143 .server-card {

144 border: 1px solid var(--border-color, #e5e7eb);

145 border-radius: 6px;

146 padding: 1rem;

147 }

148 .command-row {

149 display: flex;

150 align-items: center;

151 gap: 0.25rem;

152 }

153 .command-row code {

154 font-size: 0.75rem;

155 overflow-x: auto;

156 }

157 `}</style>

158 

159 <div className="cards-container">

160 {filteredServers.map(server => {

161 const claudeCodeCommand = generateClaudeCodeCommand(server);

162 const mcpUrl = server.urls.http || server.urls.sse;

163 const commandToShow = platform === "claudeCode" ? claudeCodeCommand : mcpUrl;

164 return <div key={server.name} className="server-card">

165 <div>

166 {server.documentation ? <a href={server.documentation}>

167 <strong>{server.name}</strong>

168 </a> : <strong>{server.name}</strong>}

169 </div>

170 

171 <p style={{

172 margin: '0.5rem 0',

173 fontSize: '0.9rem'

174 }}>

175 {server.description}

176 </p>

177 

178 {server.setupUrl && <p style={{

179 margin: '0.25rem 0',

180 fontSize: '0.8rem',

181 fontStyle: 'italic',

182 opacity: 0.7

183 }}>

184 Requires user-specific URL.{' '}

185 <a href={server.setupUrl} style={{

186 textDecoration: 'underline'

187 }}>

188 Get your URL here

189 </a>.

190 </p>}

191 

192 {commandToShow && !server.setupUrl && <>

193 <p style={{

194 display: 'block',

195 fontSize: '0.75rem',

196 fontWeight: 500,

197 minWidth: 'fit-content',

198 marginTop: '0.5rem',

199 marginBottom: 0

200 }}>

201 {platform === "claudeCode" ? "Command" : "URL"}

202 </p>

203 <div className="command-row">

204 <code>

205 {commandToShow}

206 </code>

207 </div>

208 </>}

209 </div>;

210 })}

211 </div>

212 </>;

213};

214 

215Claude Code는 AI 도구 통합을 위한 오픈 소스 표준인 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)를 통해 수백 개의 외부 도구 및 데이터 소스에 연결할 수 있습니다. MCP 서버는 Claude Code에 도구, 데이터베이스 및 API에 대한 액세스를 제공합니다.

216 

217다른 도구(예: 이슈 추적기 또는 모니터링 대시보드)에서 채팅으로 데이터를 복사하는 자신을 발견할 때 서버를 연결하세요. 연결되면 Claude는 붙여넣은 내용에서 작업하는 대신 해당 시스템을 직접 읽고 작동할 수 있습니다.

218 

219## MCP로 할 수 있는 것

220 

221MCP 서버가 연결되면 Claude Code에 다음을 요청할 수 있습니다:

222 

223* **이슈 추적기에서 기능 구현**: "JIRA 이슈 ENG-4521에 설명된 기능을 추가하고 GitHub에서 PR을 생성하세요."

224* **모니터링 데이터 분석**: "Sentry와 Statsig을 확인하여 ENG-4521에 설명된 기능의 사용량을 확인하세요."

225* **데이터베이스 쿼리**: "PostgreSQL 데이터베이스를 기반으로 기능 ENG-4521을 사용한 무작위 사용자 10명의 이메일을 찾으세요."

226* **디자인 통합**: "Slack에 게시된 새로운 Figma 디자인을 기반으로 표준 이메일 템플릿을 업데이트하세요."

227* **워크플로우 자동화**: "이 10명의 사용자를 새로운 기능에 대한 피드백 세션에 초대하는 Gmail 초안을 생성하세요."

228* **외부 이벤트에 반응**: MCP 서버는 [채널](/ko/channels)로도 작동할 수 있으며, 세션에 메시지를 푸시하므로 Claude는 자리를 비운 동안 Telegram 메시지, Discord 채팅 또는 webhook 이벤트에 반응할 수 있습니다.

229 

230## 인기 있는 MCP 서버

231 

232Claude Code에 연결할 수 있는 일반적으로 사용되는 MCP 서버는 다음과 같습니다:

233 

234<Warning>

235 타사 MCP 서버를 사용할 때는 자신의 책임하에 사용하십시오 - Anthropic은 이러한 모든 서버의 정확성이나 보안을 검증하지 않았습니다.

236 설치하는 MCP 서버를 신뢰하는지 확인하세요.

237 신뢰할 수 없는 콘텐츠를 가져올 수 있는 MCP 서버를 사용할 때는 특히 주의하세요. 이러한 서버는 프롬프트 주입 위험에 노출될 수 있습니다.

238</Warning>

239 

240<MCPServersTable platform="claudeCode" />

241 

242<Note>

243 **특정 통합이 필요하신가요?** [GitHub에서 수백 개 이상의 MCP 서버를 찾거나](https://github.com/modelcontextprotocol/servers), [MCP SDK](https://modelcontextprotocol.io/quickstart/server)를 사용하여 자신만의 서버를 구축하세요.

244</Note>

245 

246## MCP 서버 설치

247 

248MCP 서버는 필요에 따라 세 가지 방식으로 구성할 수 있습니다:

249 

250### 옵션 1: 원격 HTTP 서버 추가

251 

252HTTP 서버는 원격 MCP 서버에 연결하기 위한 권장 옵션입니다. 이는 클라우드 기반 서비스에 가장 널리 지원되는 전송 방식입니다.

253 

254```bash theme={null}

255# 기본 구문

256claude mcp add --transport http <name> <url>

257 

258# 실제 예: Notion에 연결

259claude mcp add --transport http notion https://mcp.notion.com/mcp

260 

261# Bearer 토큰을 사용한 예

262claude mcp add --transport http secure-api https://api.example.com/mcp \

263 --header "Authorization: Bearer your-token"

264```

265 

266### 옵션 2: 원격 SSE 서버 추가

267 

268<Warning>

269 SSE (Server-Sent Events) 전송은 더 이상 사용되지 않습니다. 가능한 경우 HTTP 서버를 사용하세요.

270</Warning>

271 

272```bash theme={null}

273# 기본 구문

274claude mcp add --transport sse <name> <url>

275 

276# 실제 예: Asana에 연결

277claude mcp add --transport sse asana https://mcp.asana.com/sse

278 

279# 인증 헤더를 사용한 예

280claude mcp add --transport sse private-api https://api.company.com/sse \

281 --header "X-API-Key: your-key-here"

282```

283 

284### 옵션 3: 로컬 stdio 서버 추가

285 

286Stdio 서버는 컴퓨터에서 로컬 프로세스로 실행됩니다. 시스템에 직접 액세스하거나 사용자 정의 스크립트가 필요한 도구에 이상적입니다.

287 

288```bash theme={null}

289# 기본 구문

290claude mcp add [options] <name> -- <command> [args...]

291 

292# 실제 예: Airtable 서버 추가

293claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \

294 -- npx -y airtable-mcp-server

295```

296 

297<Note>

298 **중요: 옵션 순서**

299 

300 모든 옵션(`--transport`, `--env`, `--scope`, `--header`)은 서버 이름 **앞에** 와야 합니다. `--` (이중 대시)는 서버 이름과 MCP 서버에 전달되는 명령 및 인수를 구분합니다.

301 

302 예를 들어:

303 

304 * `claude mcp add --transport stdio myserver -- npx server` → `npx server` 실행

305 * `claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080` → `KEY=value`를 환경에서 `python server.py --port 8080` 실행

306 

307 이는 Claude의 플래그와 서버의 플래그 간의 충돌을 방지합니다.

308</Note>

309 

310### 서버 관리

311 

312구성한 후에는 다음 명령으로 MCP 서버를 관리할 수 있습니다:

313 

314```bash theme={null}

315# 구성된 모든 서버 나열

316claude mcp list

317 

318# 특정 서버의 세부 정보 가져오기

319claude mcp get github

320 

321# 서버 제거

322claude mcp remove github

323 

324# (Claude Code 내에서) 서버 상태 확인

325/mcp

326```

327 

328### 동적 도구 업데이트

329 

330Claude Code는 MCP `list_changed` 알림을 지원하므로 MCP 서버가 연결을 끊었다가 다시 연결할 필요 없이 사용 가능한 도구, 프롬프트 및 리소스를 동적으로 업데이트할 수 있습니다. MCP 서버가 `list_changed` 알림을 보내면 Claude Code는 해당 서버에서 사용 가능한 기능을 자동으로 새로 고칩니다.

331 

332### 자동 재연결

333 

334HTTP 또는 SSE 서버가 세션 중에 연결이 끊어지면 Claude Code는 지수 백오프를 사용하여 자동으로 재연결합니다: 최대 5번의 시도, 1초 지연으로 시작하여 매번 두 배씩 증가합니다. 서버는 재연결이 진행 중인 동안 `/mcp`에서 보류 중으로 나타납니다. 5번의 실패 시도 후 서버는 실패로 표시되며 `/mcp`에서 수동으로 다시 시도할 수 있습니다. Stdio 서버는 로컬 프로세스이며 자동으로 재연결되지 않습니다.

335 

336HTTP 또는 SSE 서버가 시작 시 초기 연결에 실패할 때도 동일한 백오프가 적용됩니다. v2.1.121부터 Claude Code는 5xx 응답, 연결 거부 또는 시간 초과와 같은 일시적 오류에 대해 초기 연결을 최대 3번 재시도한 후, 여전히 연결할 수 없으면 서버를 실패로 표시합니다. 인증 및 찾을 수 없음 오류는 해결하기 위해 구성 변경이 필요하므로 재시도되지 않습니다.

337 

338### 채널을 사용한 메시지 푸시

339 

340MCP 서버는 또한 메시지를 세션에 직접 푸시할 수 있으므로 Claude는 CI 결과, 모니터링 경고 또는 채팅 메시지와 같은 외부 이벤트에 반응할 수 있습니다. 이를 활성화하려면 서버가 `claude/channel` 기능을 선언하고 시작 시 `--channels` 플래그로 옵트인합니다. 공식적으로 지원되는 채널을 사용하려면 [채널](/ko/channels)을 참조하거나, 자신만의 채널을 구축하려면 [채널 참조](/ko/channels-reference)를 참조하세요.

341 

342<Tip>

343 팁:

344 

345 * `--scope` 플래그를 사용하여 구성이 저장되는 위치를 지정하세요:

346 * `local` (기본값): 현재 프로젝트에서만 사용자에게만 사용 가능 (이전 버전에서는 `project`라고 불렸음)

347 * `project`: `.mcp.json` 파일을 통해 프로젝트의 모든 사람과 공유

348 * `user`: 모든 프로젝트에서 사용자에게 사용 가능 (이전 버전에서는 `global`이라고 불렸음)

349 * `--env` 플래그로 환경 변수를 설정하세요 (예: `--env KEY=value`)

350 * `MCP_TIMEOUT` 환경 변수를 사용하여 MCP 서버 시작 시간 초과를 구성하세요 (예: `MCP_TIMEOUT=10000 claude`는 10초 시간 초과를 설정)

351 * Claude Code는 MCP 도구 출력이 10,000 토큰을 초과할 때 경고를 표시합니다. 이 제한을 늘리려면 `MAX_MCP_OUTPUT_TOKENS` 환경 변수를 설정하세요 (예: `MAX_MCP_OUTPUT_TOKENS=50000`)

352 * OAuth 2.0 인증이 필요한 원격 서버로 인증하려면 `/mcp`를 사용하세요

353</Tip>

354 

355### 플러그인 제공 MCP 서버

356 

357[플러그인](/ko/plugins)은 MCP 서버를 번들로 제공할 수 있으며, 플러그인이 활성화되면 도구 및 통합을 자동으로 제공합니다. 플러그인 MCP 서버는 사용자 구성 서버와 동일하게 작동합니다.

358 

359**플러그인 MCP 서버의 작동 방식**:

360 

361* 플러그인은 플러그인 루트의 `.mcp.json` 또는 `plugin.json`에 인라인으로 MCP 서버를 정의합니다

362* 플러그인이 활성화되면 MCP 서버가 자동으로 시작됩니다

363* 플러그인 MCP 도구는 수동으로 구성된 MCP 도구와 함께 나타납니다

364* 플러그인 서버는 플러그인 설치를 통해 관리됩니다 (`/mcp` 명령이 아님)

365 

366**플러그인 MCP 구성 예**:

367 

368플러그인 루트의 `.mcp.json`:

369 

370```json theme={null}

371{

372 "mcpServers": {

373 "database-tools": {

374 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",

375 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],

376 "env": {

377 "DB_URL": "${DB_URL}"

378 }

379 }

380 }

381}

382```

383 

384또는 `plugin.json`에 인라인:

385 

386```json theme={null}

387{

388 "name": "my-plugin",

389 "mcpServers": {

390 "plugin-api": {

391 "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",

392 "args": ["--port", "8080"]

393 }

394 }

395}

396```

397 

398**플러그인 MCP 기능**:

399 

400* **자동 라이프사이클**: 세션 시작 시 활성화된 플러그인의 서버가 자동으로 연결됩니다. 세션 중에 플러그인을 활성화하거나 비활성화하면 `/reload-plugins`를 실행하여 MCP 서버를 연결하거나 연결 해제합니다

401* **환경 변수**: 번들된 플러그인 파일에 `${CLAUDE_PLUGIN_ROOT}` 사용 및 플러그인 업데이트를 유지하는 [지속적인 상태](/ko/plugins-reference#persistent-data-directory)에 `${CLAUDE_PLUGIN_DATA}` 사용

402* **사용자 환경 액세스**: 수동으로 구성된 서버와 동일한 환경 변수에 액세스

403* **여러 전송 유형**: stdio, SSE 및 HTTP 전송 지원 (전송 지원은 서버에 따라 다를 수 있음)

404 

405**플러그인 MCP 서버 보기**:

406 

407```bash theme={null}

408# Claude Code 내에서 플러그인 서버를 포함한 모든 MCP 서버 보기

409/mcp

410```

411 

412플러그인 서버는 플러그인에서 온 것을 나타내는 표시기와 함께 목록에 나타납니다.

413 

414**플러그인 MCP 서버의 이점**:

415 

416* **번들 배포**: 도구 및 서버가 함께 패키징됨

417* **자동 설정**: 수동 MCP 구성이 필요 없음

418* **팀 일관성**: 플러그인이 설치되면 모든 사람이 동일한 도구를 얻음

419 

420플러그인과 함께 MCP 서버를 번들로 제공하는 방법에 대한 자세한 내용은 [플러그인 구성 요소 참조](/ko/plugins-reference#mcp-servers)를 참조하세요.

421 

422## MCP 설치 범위

423 

424MCP 서버는 세 가지 범위에서 구성할 수 있습니다. 선택한 범위는 서버가 로드되는 프로젝트와 구성이 팀과 공유되는지 여부를 제어합니다.

425 

426| 범위 | 로드 위치 | 팀과 공유 | 저장 위치 |

427| ---------------------- | -------- | ------------ | -------------------- |

428| [로컬](#local-scope) | 현재 프로젝트만 | 아니오 | `~/.claude.json` |

429| [프로젝트](#project-scope) | 현재 프로젝트만 | 예, 버전 제어를 통해 | 프로젝트 루트의 `.mcp.json` |

430| [사용자](#user-scope) | 모든 프로젝트 | 아니오 | `~/.claude.json` |

431 

432### 로컬 범위

433 

434로컬 범위는 기본값입니다. 로컬 범위 서버는 추가한 프로젝트에서만 로드되며 사용자에게만 비공개입니다. Claude Code는 해당 프로젝트의 경로 아래 `~/.claude.json`에 저장하므로 다른 프로젝트에는 동일한 서버가 나타나지 않습니다. 개인 개발 서버, 실험적 구성 또는 버전 제어에 포함하고 싶지 않은 자격 증명이 있는 서버에 로컬 범위를 사용하세요.

435 

436<Note>

437 MCP 서버의 "로컬 범위"라는 용어는 일반 로컬 설정과 다릅니다. MCP 로컬 범위 서버는 `~/.claude.json` (홈 디렉토리)에 저장되고, 일반 로컬 설정은 `.claude/settings.local.json` (프로젝트 디렉토리)을 사용합니다. 설정 파일 위치에 대한 자세한 내용은 [설정](/ko/settings#settings-files)을 참조하세요.

438</Note>

439 

440```bash theme={null}

441# 로컬 범위 서버 추가 (기본값)

442claude mcp add --transport http stripe https://mcp.stripe.com

443 

444# 명시적으로 로컬 범위 지정

445claude mcp add --transport http stripe --scope local https://mcp.stripe.com

446```

447 

448`/path/to/your/project`에서 실행할 때 명령은 `~/.claude.json` 내의 현재 프로젝트 항목에 서버를 작성합니다. 아래 예는 결과를 보여줍니다:

449 

450```json theme={null}

451{

452 "projects": {

453 "/path/to/your/project": {

454 "mcpServers": {

455 "stripe": {

456 "type": "http",

457 "url": "https://mcp.stripe.com"

458 }

459 }

460 }

461 }

462}

463```

464 

465### 프로젝트 범위

466 

467프로젝트 범위 서버는 프로젝트 루트 디렉토리의 `.mcp.json` 파일에 구성을 저장하여 팀 협업을 가능하게 합니다. 이 파일은 버전 제어에 체크인되도록 설계되어 모든 팀 멤버가 동일한 MCP 도구 및 서비스에 액세스할 수 있도록 합니다. 프로젝트 범위 서버를 추가하면 Claude Code는 자동으로 이 파일을 생성하거나 적절한 구성 구조로 업데이트합니다.

468 

469```bash theme={null}

470# 프로젝트 범위 서버 추가

471claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

472```

473 

474결과 `.mcp.json` 파일은 표준화된 형식을 따릅니다:

475 

476```json theme={null}

477{

478 "mcpServers": {

479 "shared-server": {

480 "command": "/path/to/server",

481 "args": [],

482 "env": {}

483 }

484 }

485}

486```

487 

488보안상의 이유로 Claude Code는 `.mcp.json` 파일의 프로젝트 범위 서버를 사용하기 전에 승인을 요청합니다. 이러한 승인 선택을 재설정해야 하는 경우 `claude mcp reset-project-choices` 명령을 사용하세요.

489 

490### 사용자 범위

491 

492사용자 범위 서버는 `~/.claude.json`에 저장되며 교차 프로젝트 접근성을 제공하므로 컴퓨터의 모든 프로젝트에서 사용할 수 있으면서 사용자 계정에만 비공개입니다. 이 범위는 개인 유틸리티 서버, 개발 도구 또는 다양한 프로젝트에서 자주 사용하는 서비스에 적합합니다.

493 

494```bash theme={null}

495# 사용자 서버 추가

496claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

497```

498 

499### 범위 계층 및 우선순위

500 

501동일한 이름의 서버가 둘 이상의 위치에 정의되면 Claude Code는 가장 높은 우선순위 소스의 정의를 사용하여 한 번 연결합니다:

502 

5031. 로컬 범위

5042. 프로젝트 범위

5053. 사용자 범위

5064. [플러그인 제공 서버](/ko/plugins)

5075. [Claude.ai 커넥터](#use-mcp-servers-from-claude-ai)

508 

509세 범위는 이름으로 중복을 일치시킵니다. 플러그인과 커넥터는 엔드포인트로 일치하므로 위의 서버와 동일한 URL 또는 명령을 가리키는 것은 중복으로 처리됩니다.

510 

511### `.mcp.json`의 환경 변수 확장

512 

513Claude Code는 `.mcp.json` 파일의 환경 변수 확장을 지원하므로 팀이 구성을 공유하면서 머신 특정 경로 및 API 키와 같은 민감한 값에 대한 유연성을 유지할 수 있습니다.

514 

515**지원되는 구문:**

516 

517* `${VAR}` - 환경 변수 `VAR`의 값으로 확장

518* `${VAR:-default}` - `VAR`이 설정되면 확장, 그렇지 않으면 `default` 사용

519 

520**확장 위치:**

521환경 변수는 다음에서 확장할 수 있습니다:

522 

523* `command` - 서버 실행 파일 경로

524* `args` - 명령줄 인수

525* `env` - 서버에 전달되는 환경 변수

526* `url` - HTTP 서버 유형의 경우

527* `headers` - HTTP 서버 인증의 경우

528 

529**변수 확장을 사용한 예**:

530 

531```json theme={null}

532{

533 "mcpServers": {

534 "api-server": {

535 "type": "http",

536 "url": "${API_BASE_URL:-https://api.example.com}/mcp",

537 "headers": {

538 "Authorization": "Bearer ${API_KEY}"

539 }

540 }

541 }

542}

543```

544 

545필수 환경 변수가 설정되지 않았고 기본값이 없으면 Claude Code는 구성을 구문 분석하지 못합니다.

546 

547## 실제 예

548 

549{/* ### 예: Playwright로 브라우저 테스트 자동화

550 

551```bash

552claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

553```

554 

555그런 다음 브라우저 테스트를 작성하고 실행합니다:

556 

557```text

558test@example.com으로 로그인 흐름이 작동하는지 테스트

559```

560```text

561모바일에서 체크아웃 페이지의 스크린샷 촬영

562```

563```text

564검색 기능이 결과를 반환하는지 확인

565``` */}

566 

567### 예: Sentry로 오류 모니터링

568 

569```bash theme={null}

570claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

571```

572 

573Sentry 계정으로 인증합니다:

574 

575```text theme={null}

576/mcp

577```

578 

579그런 다음 프로덕션 문제를 디버깅합니다:

580 

581```text theme={null}

582지난 24시간 동안 가장 일반적인 오류는 무엇입니까?

583```

584 

585```text theme={null}

586오류 ID abc123의 스택 추적을 보여주세요

587```

588 

589```text theme={null}

590어떤 배포가 이러한 새로운 오류를 도입했습니까?

591```

592 

593### 예: 코드 검토를 위해 GitHub에 연결

594 

595GitHub의 원격 MCP 서버는 헤더로 전달된 GitHub 개인 액세스 토큰으로 인증합니다. 하나를 얻으려면 [GitHub 토큰 설정](https://github.com/settings/personal-access-tokens)을 열고, Claude가 작업하려는 리포지토리에 액세스할 수 있는 새로운 세분화된 토큰을 생성한 다음 서버를 추가하세요:

596 

597```bash theme={null}

598claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \

599 --header "Authorization: Bearer YOUR_GITHUB_PAT"

600```

601 

602그런 다음 GitHub로 작업합니다:

603 

604```text theme={null}

605PR #456을 검토하고 개선 사항을 제안하세요

606```

607 

608```text theme={null}

609방금 발견한 버그에 대한 새 이슈를 생성하세요

610```

611 

612```text theme={null}

613나에게 할당된 모든 열린 PR을 보여주세요

614```

615 

616### 예: PostgreSQL 데이터베이스 쿼리

617 

618```bash theme={null}

619claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \

620 --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

621```

622 

623그런 다음 자연스럽게 데이터베이스를 쿼리합니다:

624 

625```text theme={null}

626이번 달 총 수익은 얼마입니까?

627```

628 

629```text theme={null}

630주문 테이블의 스키마를 보여주세요

631```

632 

633```text theme={null}

634지난 90일 동안 구매하지 않은 고객을 찾으세요

635```

636 

637## 원격 MCP 서버로 인증

638 

639많은 클라우드 기반 MCP 서버는 인증이 필요합니다. Claude Code는 보안 연결을 위해 OAuth 2.0을 지원합니다.

640 

641<Steps>

642 <Step title="인증이 필요한 서버 추가">

643 예를 들어:

644 

645 ```bash theme={null}

646 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

647 ```

648 </Step>

649 

650 <Step title="Claude Code 내에서 /mcp 명령 사용">

651 Claude Code에서 다음 명령을 사용합니다:

652 

653 ```text theme={null}

654 /mcp

655 ```

656 

657 그런 다음 브라우저에서 로그인 단계를 따릅니다.

658 </Step>

659</Steps>

660 

661<Tip>

662 팁:

663 

664 * 인증 토큰은 안전하게 저장되고 자동으로 새로 고쳐집니다

665 * `/mcp` 메뉴에서 "Clear authentication"을 사용하여 액세스를 취소합니다

666 * 브라우저가 자동으로 열리지 않으면 제공된 URL을 복사하여 수동으로 엽니다

667 * 인증 후 브라우저 리디렉션이 연결 오류로 실패하면 브라우저의 주소 표시줄에서 전체 콜백 URL을 복사하여 Claude Code에 나타나는 URL 프롬프트에 붙여넣습니다

668 * OAuth 인증은 HTTP 서버에서 작동합니다

669</Tip>

670 

671### 고정 OAuth 콜백 포트 사용

672 

673일부 MCP 서버는 미리 등록된 특정 리디렉션 URI가 필요합니다. 기본적으로 Claude Code는 OAuth 콜백을 위해 무작위로 사용 가능한 포트를 선택합니다. `--callback-port`를 사용하여 포트를 고정하여 `http://localhost:PORT/callback` 형식의 사전 등록된 리디렉션 URI와 일치하도록 합니다.

674 

675`--callback-port`를 단독으로 사용할 수 있습니다 (동적 클라이언트 등록 포함) 또는 `--client-id`와 함께 사용할 수 있습니다 (사전 구성된 자격 증명 포함).

676 

677```bash theme={null}

678# 동적 클라이언트 등록을 사용한 고정 콜백 포트

679claude mcp add --transport http \

680 --callback-port 8080 \

681 my-server https://mcp.example.com/mcp

682```

683 

684### 사전 구성된 OAuth 자격 증명 사용

685 

686일부 MCP 서버는 자동 OAuth 설정을 지원하지 않습니다. "Incompatible auth server: does not support dynamic client registration"과 같은 오류가 표시되면 서버에 사전 구성된 자격 증명이 필요합니다. Claude Code는 또한 동적 클라이언트 등록 대신 클라이언트 ID 메타데이터 문서 (CIMD)를 사용하는 서버를 지원하며 자동으로 검색합니다. 자동 검색이 실패하면 먼저 서버의 개발자 포털을 통해 OAuth 앱을 등록한 다음 서버를 추가할 때 자격 증명을 제공합니다.

687 

688<Steps>

689 <Step title="서버로 OAuth 앱 등록">

690 서버의 개발자 포털을 통해 앱을 생성하고 클라이언트 ID와 클라이언트 시크릿을 기록합니다.

691 

692 많은 서버는 리디렉션 URI도 필요합니다. 그렇다면 포트를 선택하고 `http://localhost:PORT/callback` 형식으로 리디렉션 URI를 등록합니다. 다음 단계에서 `--callback-port`와 함께 동일한 포트를 사용합니다.

693 </Step>

694 

695 <Step title="자격 증명으로 서버 추가">

696 다음 방법 중 하나를 선택합니다. `--callback-port`에 사용되는 포트는 사용 가능한 모든 포트일 수 있습니다. 이전 단계에서 등록한 리디렉션 URI와 일치하기만 하면 됩니다.

697 

698 <Tabs>

699 <Tab title="claude mcp add">

700 `--client-id`를 사용하여 앱의 클라이언트 ID를 전달합니다. `--client-secret` 플래그는 마스킹된 입력으로 시크릿을 요청합니다:

701 

702 ```bash theme={null}

703 claude mcp add --transport http \

704 --client-id your-client-id --client-secret --callback-port 8080 \

705 my-server https://mcp.example.com/mcp

706 ```

707 </Tab>

708 

709 <Tab title="claude mcp add-json">

710 JSON 구성에 `oauth` 객체를 포함하고 `--client-secret`을 별도의 플래그로 전달합니다:

711 

712 ```bash theme={null}

713 claude mcp add-json my-server \

714 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \

715 --client-secret

716 ```

717 </Tab>

718 

719 <Tab title="claude mcp add-json (콜백 포트만)">

720 동적 클라이언트 등록을 사용하면서 포트를 고정하려면 클라이언트 ID 없이 `--callback-port`를 사용합니다:

721 

722 ```bash theme={null}

723 claude mcp add-json my-server \

724 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

725 ```

726 </Tab>

727 

728 <Tab title="CI / 환경 변수">

729 환경 변수를 통해 시크릿을 설정하여 대화형 프롬프트를 건너뜁니다:

730 

731 ```bash theme={null}

732 MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \

733 --client-id your-client-id --client-secret --callback-port 8080 \

734 my-server https://mcp.example.com/mcp

735 ```

736 </Tab>

737 </Tabs>

738 </Step>

739 

740 <Step title="Claude Code에서 인증">

741 Claude Code에서 `/mcp`를 실행하고 브라우저 로그인 흐름을 따릅니다.

742 </Step>

743</Steps>

744 

745<Tip>

746 팁:

747 

748 * 클라이언트 시크릿은 구성에 저장되지 않고 시스템 키체인 (macOS) 또는 자격 증명 파일에 안전하게 저장됩니다

749 * 서버가 시크릿이 없는 공개 OAuth 클라이언트를 사용하는 경우 `--client-secret` 없이 `--client-id`만 사용합니다

750 * `--callback-port`는 `--client-id`와 함께 또는 없이 사용할 수 있습니다

751 * 이러한 플래그는 HTTP 및 SSE 전송에만 적용됩니다. stdio 서버에는 영향을 주지 않습니다

752 * `claude mcp get <name>`을 사용하여 OAuth 자격 증명이 서버에 대해 구성되었는지 확인합니다

753</Tip>

754 

755### OAuth 메타데이터 검색 재정의

756 

757특정 OAuth 인증 서버 메타데이터 URL을 가리켜 기본 검색 체인을 우회하도록 Claude Code를 설정합니다. MCP 서버의 표준 엔드포인트가 오류를 반환하거나 내부 프록시를 통해 검색을 라우팅하려는 경우에 설정합니다. 기본적으로 Claude Code는 먼저 `/.well-known/oauth-protected-resource`에서 RFC 9728 보호된 리소스 메타데이터를 확인한 다음 `/.well-known/oauth-authorization-server`에서 RFC 8414 인증 서버 메타데이터로 돌아갑니다.

758 

759`.mcp.json`의 서버 구성의 `oauth` 객체에 `authServerMetadataUrl`을 설정합니다:

760 

761```json theme={null}

762{

763 "mcpServers": {

764 "my-server": {

765 "type": "http",

766 "url": "https://mcp.example.com/mcp",

767 "oauth": {

768 "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"

769 }

770 }

771 }

772}

773```

774 

775URL은 `https://`를 사용해야 합니다. `authServerMetadataUrl`은 Claude Code v2.1.64 이상이 필요합니다. 메타데이터 URL의 `scopes_supported`는 업스트림 서버가 광고하는 범위를 재정의합니다.

776 

777### OAuth 범위 제한

778 

779`oauth.scopes`를 설정하여 인증 흐름 중에 Claude Code가 요청하는 범위를 고정합니다. 이는 업스트림 인증 서버가 광고하는 것보다 더 많은 범위를 부여하고 싶지 않을 때 MCP 서버를 보안 팀이 승인한 부분 집합으로 제한하는 지원되는 방법입니다. 값은 RFC 6749 §3.3의 `scope` 매개변수 형식과 일치하는 단일 공백으로 구분된 문자열입니다.

780 

781```json theme={null}

782{

783 "mcpServers": {

784 "slack": {

785 "type": "http",

786 "url": "https://mcp.slack.com/mcp",

787 "oauth": {

788 "scopes": "channels:read chat:write search:read"

789 }

790 }

791 }

792}

793```

794 

795`oauth.scopes`는 `authServerMetadataUrl`과 서버가 `/.well-known`에서 검색하는 범위 모두보다 우선합니다. 설정하지 않으면 MCP 서버가 요청된 범위 집합을 결정합니다.

796 

797인증 서버가 `scopes_supported`에서 `offline_access`를 광고하면 Claude Code는 액세스 토큰을 새로운 브라우저 로그인 없이 새로 고칠 수 있도록 고정된 범위에 추가합니다.

798 

799서버가 나중에 도구 호출에 대해 403 `insufficient_scope`을 반환하면 Claude Code는 동일한 고정된 범위로 다시 인증합니다. 필요한 도구가 고정된 범위 외의 범위를 요구할 때 `oauth.scopes`를 확대합니다.

800 

801### 사용자 정의 인증을 위한 동적 헤더 사용

802 

803MCP 서버가 OAuth (예: Kerberos, 단기 토큰 또는 내부 SSO)가 아닌 다른 인증 체계를 사용하는 경우 `headersHelper`를 사용하여 연결 시간에 요청 헤더를 생성합니다. Claude Code는 명령을 실행하고 출력을 연결 헤더에 병합합니다.

804 

805```json theme={null}

806{

807 "mcpServers": {

808 "internal-api": {

809 "type": "http",

810 "url": "https://mcp.internal.example.com",

811 "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"

812 }

813 }

814}

815```

816 

817명령은 인라인일 수도 있습니다:

818 

819```json theme={null}

820{

821 "mcpServers": {

822 "internal-api": {

823 "type": "http",

824 "url": "https://mcp.internal.example.com",

825 "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"

826 }

827 }

828}

829```

830 

831**요구 사항:**

832 

833* 명령은 JSON 객체의 문자열 키-값 쌍을 stdout에 작성해야 합니다

834* 명령은 10초 시간 초과를 사용하여 셸에서 실행됩니다

835* 동적 헤더는 동일한 이름의 정적 `headers`를 재정의합니다

836 

837헬퍼는 각 연결 (세션 시작 및 재연결 시)에서 새로 실행됩니다. 캐싱이 없으므로 스크립트는 토큰 재사용을 담당합니다.

838 

839Claude Code는 헬퍼를 실행할 때 다음 환경 변수를 설정합니다:

840 

841| 변수 | 값 |

842| :---------------------------- | :---------- |

843| `CLAUDE_CODE_MCP_SERVER_NAME` | MCP 서버의 이름 |

844| `CLAUDE_CODE_MCP_SERVER_URL` | MCP 서버의 URL |

845 

846이를 사용하여 여러 MCP 서버를 제공하는 단일 헬퍼 스크립트를 작성합니다.

847 

848<Note>

849 `headersHelper`는 임의의 셸 명령을 실행합니다. 프로젝트 또는 로컬 범위에서 정의될 때 작업 공간 신뢰 대화 상자를 수락한 후에만 실행됩니다.

850</Note>

851 

852## JSON 구성에서 MCP 서버 추가

853 

854MCP 서버에 대한 JSON 구성이 있는 경우 직접 추가할 수 있습니다:

855 

856<Steps>

857 <Step title="JSON에서 MCP 서버 추가">

858 ```bash theme={null}

859 # 기본 구문

860 claude mcp add-json <name> '<json>'

861 

862 # 예: JSON 구성으로 HTTP 서버 추가

863 claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

864 

865 # 예: JSON 구성으로 stdio 서버 추가

866 claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

867 

868 # 예: 사전 구성된 OAuth 자격 증명으로 HTTP 서버 추가

869 claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

870 ```

871 </Step>

872 

873 <Step title="서버가 추가되었는지 확인">

874 ```bash theme={null}

875 claude mcp get weather-api

876 ```

877 </Step>

878</Steps>

879 

880<Tip>

881 팁:

882 

883 * JSON이 셸에서 올바르게 이스케이프되었는지 확인합니다

884 * JSON은 MCP 서버 구성 스키마를 준수해야 합니다

885 * `--scope user`를 사용하여 프로젝트 특정 구성 대신 사용자 구성에 서버를 추가할 수 있습니다

886</Tip>

887 

888## Claude Desktop에서 MCP 서버 가져오기

889 

890Claude Desktop에서 MCP 서버를 이미 구성한 경우 가져올 수 있습니다:

891 

892<Steps>

893 <Step title="Claude Desktop에서 서버 가져오기">

894 ```bash theme={null}

895 # 기본 구문

896 claude mcp add-from-claude-desktop

897 ```

898 </Step>

899 

900 <Step title="가져올 서버 선택">

901 명령을 실행한 후 가져올 서버를 선택할 수 있는 대화형 대화 상자가 표시됩니다.

902 </Step>

903 

904 <Step title="서버가 가져와졌는지 확인">

905 ```bash theme={null}

906 claude mcp list

907 ```

908 </Step>

909</Steps>

910 

911<Tip>

912 팁:

913 

914 * 이 기능은 macOS 및 Windows Subsystem for Linux (WSL)에서만 작동합니다

915 * 이러한 플랫폼의 표준 위치에서 Claude Desktop 구성 파일을 읽습니다

916 * `--scope user` 플래그를 사용하여 사용자 구성에 서버를 추가합니다

917 * 가져온 서버는 Claude Desktop과 동일한 이름을 갖습니다

918 * 동일한 이름의 서버가 이미 존재하면 숫자 접미사가 붙습니다 (예: `server_1`)

919</Tip>

920 

921## Claude.ai에서 MCP 서버 사용

922 

923[Claude.ai](https://claude.ai) 계정으로 Claude Code에 로그인한 경우 Claude.ai에서 추가한 MCP 서버는 Claude Code에서 자동으로 사용 가능합니다:

924 

925<Steps>

926 <Step title="Claude.ai에서 MCP 서버 구성">

927 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서버를 추가합니다. Team 및 Enterprise 플랜에서는 관리자만 서버를 추가할 수 있습니다.

928 </Step>

929 

930 <Step title="MCP 서버 인증">

931 Claude.ai에서 필요한 인증 단계를 완료합니다.

932 </Step>

933 

934 <Step title="Claude Code에서 서버 보기 및 관리">

935 Claude Code에서 다음 명령을 사용합니다:

936 

937 ```text theme={null}

938 /mcp

939 ```

940 

941 Claude.ai 서버는 Claude.ai에서 온 것을 나타내는 표시기와 함께 목록에 나타납니다.

942 </Step>

943</Steps>

944 

945Claude Code에서 claude.ai MCP 서버를 비활성화하려면 `ENABLE_CLAUDEAI_MCP_SERVERS` 환경 변수를 `false`로 설정합니다:

946 

947```bash theme={null}

948ENABLE_CLAUDEAI_MCP_SERVERS=false claude

949```

950 

951## Claude Code를 MCP 서버로 사용

952 

953Claude Code 자체를 다른 애플리케이션이 연결할 수 있는 MCP 서버로 사용할 수 있습니다:

954 

955```bash theme={null}

956# Claude를 stdio MCP 서버로 시작

957claude mcp serve

958```

959 

960claude\_desktop\_config.json에 이 구성을 추가하여 Claude Desktop에서 사용할 수 있습니다:

961 

962```json theme={null}

963{

964 "mcpServers": {

965 "claude-code": {

966 "type": "stdio",

967 "command": "claude",

968 "args": ["mcp", "serve"],

969 "env": {}

970 }

971 }

972}

973```

974 

975<Warning>

976 **실행 파일 경로 구성**: `command` 필드는 Claude Code 실행 파일을 참조해야 합니다. `claude` 명령이 시스템의 PATH에 없으면 실행 파일의 전체 경로를 지정해야 합니다.

977 

978 전체 경로를 찾으려면:

979 

980 ```bash theme={null}

981 which claude

982 ```

983 

984 그런 다음 구성에서 전체 경로를 사용합니다:

985 

986 ```json theme={null}

987 {

988 "mcpServers": {

989 "claude-code": {

990 "type": "stdio",

991 "command": "/full/path/to/claude",

992 "args": ["mcp", "serve"],

993 "env": {}

994 }

995 }

996 }

997 ```

998 

999 올바른 실행 파일 경로가 없으면 `spawn claude ENOENT`와 같은 오류가 발생합니다.

1000</Warning>

1001 

1002<Tip>

1003 팁:

1004 

1005 * 서버는 View, Edit, LS 등과 같은 Claude의 도구에 대한 액세스를 제공합니다

1006 * Claude Desktop에서 Claude에게 디렉토리의 파일을 읽고, 편집하는 등을 요청해 보세요

1007 * 이 MCP 서버는 Claude Code의 도구만 MCP 클라이언트에 노출하므로 클라이언트는 개별 도구 호출에 대한 사용자 확인을 구현할 책임이 있습니다.

1008</Tip>

1009 

1010## MCP 출력 제한 및 경고

1011 

1012MCP 도구가 큰 출력을 생성할 때 Claude Code는 토큰 사용량을 관리하여 대화 컨텍스트가 압도되지 않도록 합니다:

1013 

1014* **출력 경고 임계값**: Claude Code는 MCP 도구 출력이 10,000 토큰을 초과할 때 경고를 표시합니다

1015* **구성 가능한 제한**: `MAX_MCP_OUTPUT_TOKENS` 환경 변수를 사용하여 최대 허용 MCP 출력 토큰을 조정할 수 있습니다

1016* **기본 제한**: 기본 최대값은 25,000 토큰입니다

1017* **범위**: 환경 변수는 자신의 제한을 선언하지 않는 도구에 적용됩니다. [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool)를 설정하는 도구는 `MAX_MCP_OUTPUT_TOKENS`이 설정된 것과 관계없이 텍스트 콘텐츠에 대해 해당 값을 사용합니다. 이미지 데이터를 반환하는 도구는 여전히 `MAX_MCP_OUTPUT_TOKENS`의 영향을 받습니다

1018 

1019큰 출력을 생성하는 도구의 제한을 늘리려면:

1020 

1021```bash theme={null}

1022export MAX_MCP_OUTPUT_TOKENS=50000

1023claude

1024```

1025 

1026이는 다음을 수행하는 MCP 서버로 작업할 때 특히 유용합니다:

1027 

1028* 대규모 데이터 세트 또는 데이터베이스 쿼리

1029* 상세한 보고서 또는 문서 생성

1030* 광범위한 로그 파일 또는 디버깅 정보 처리

1031 

1032### 특정 도구의 제한 늘리기

1033 

1034MCP 서버를 구축하는 경우 도구의 `tools/list` 응답 항목에서 `_meta["anthropic/maxResultSizeChars"]`를 설정하여 개별 도구가 기본 디스크 유지 임계값보다 큰 결과를 반환할 수 있습니다. Claude Code는 해당 도구의 임계값을 주석 처리된 값으로 올립니다 (최대 500,000자의 하드 상한까지).

1035 

1036이는 데이터베이스 스키마 또는 전체 파일 트리와 같이 본질적으로 크지만 필요한 출력을 반환하는 도구에 유용합니다. 주석 처리 없이 기본 임계값을 초과하는 결과는 디스크에 유지되고 대화에서 파일 참조로 대체됩니다.

1037 

1038```json theme={null}

1039{

1040 "name": "get_schema",

1041 "description": "Returns the full database schema",

1042 "_meta": {

1043 "anthropic/maxResultSizeChars": 200000

1044 }

1045}

1046```

1047 

1048주석 처리는 텍스트 콘텐츠에 대해 `MAX_MCP_OUTPUT_TOKENS`과 독립적으로 적용되므로 사용자는 도구가 선언하는 도구에 대해 환경 변수를 올릴 필요가 없습니다. 이미지 데이터를 반환하는 도구는 여전히 토큰 제한의 영향을 받습니다.

1049 

1050<Warning>

1051 특정 MCP 서버에서 자주 출력 경고가 발생하면 `MAX_MCP_OUTPUT_TOKENS` 제한을 늘리는 것을 고려하세요. 또한 서버 작성자에게 `anthropic/maxResultSizeChars` 주석을 추가하거나 응답을 페이지 매김하도록 요청할 수 있습니다. 주석은 이미지 콘텐츠를 반환하는 도구에는 영향을 주지 않습니다. 이러한 경우 `MAX_MCP_OUTPUT_TOKENS`을 올리는 것이 유일한 옵션입니다.

1052</Warning>

1053 

1054## MCP 리소스 요청에 응답

1055 

1056MCP 서버는 작업 중에 구조화된 입력을 요청할 수 있습니다. 서버가 자체적으로 얻을 수 없는 정보가 필요할 때 Claude Code는 대화형 대화 상자를 표시하고 응답을 서버에 다시 전달합니다. 사용자 측에서 구성이 필요하지 않습니다: 서버가 요청할 때 리소스 요청 대화 상자가 자동으로 나타납니다.

1057 

1058서버는 두 가지 방식으로 입력을 요청할 수 있습니다:

1059 

1060* **양식 모드**: Claude Code는 서버에서 정의한 양식 필드가 있는 대화 상자를 표시합니다 (예: 사용자 이름 및 암호 프롬프트). 필드를 입력하고 제출합니다.

1061* **URL 모드**: Claude Code는 인증 또는 승인을 위해 브라우저 URL을 엽니다. 브라우저에서 흐름을 완료한 다음 CLI에서 확인합니다.

1062 

1063리소스 요청에 자동으로 응답하려면 [`Elicitation` 훅](/ko/hooks#Elicitation)을 사용하세요.

1064 

1065리소스 요청을 사용하는 MCP 서버를 구축하는 경우 [MCP 리소스 요청 사양](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation)에서 프로토콜 세부 정보 및 스키마 예를 참조하세요.

1066 

1067## MCP 리소스 사용

1068 

1069MCP 서버는 파일을 참조하는 방식과 유사하게 @ 멘션을 사용하여 참조할 수 있는 리소스를 노출할 수 있습니다.

1070 

1071### MCP 리소스 참조

1072 

1073<Steps>

1074 <Step title="사용 가능한 리소스 나열">

1075 프롬프트에 `@`를 입력하여 연결된 모든 MCP 서버의 사용 가능한 리소스를 확인합니다. 리소스는 자동 완성 메뉴의 파일과 함께 나타납니다.

1076 </Step>

1077 

1078 <Step title="특정 리소스 참조">

1079 `@server:protocol://resource/path` 형식을 사용하여 리소스를 참조합니다:

1080 

1081 ```text theme={null}

1082 @github:issue://123을 분석하고 수정 사항을 제안할 수 있나요?

1083 ```

1084 

1085 ```text theme={null}

1086 @docs:file://api/authentication의 API 문서를 검토해 주세요

1087 ```

1088 </Step>

1089 

1090 <Step title="여러 리소스 참조">

1091 단일 프롬프트에서 여러 리소스를 참조할 수 있습니다:

1092 

1093 ```text theme={null}

1094 @postgres:schema://users와 @docs:file://database/user-model을 비교하세요

1095 ```

1096 </Step>

1097</Steps>

1098 

1099<Tip>

1100 팁:

1101 

1102 * 리소스는 참조될 때 자동으로 가져와지고 첨부 파일로 포함됩니다

1103 * 리소스 경로는 @ 멘션 자동 완성에서 퍼지 검색 가능합니다

1104 * Claude Code는 서버가 지원할 때 MCP 리소스를 나열하고 읽을 수 있는 도구를 자동으로 제공합니다

1105 * 리소스는 MCP 서버가 제공하는 모든 유형의 콘텐츠를 포함할 수 있습니다 (텍스트, JSON, 구조화된 데이터 등)

1106</Tip>

1107 

1108## MCP Tool Search로 확장

1109 

1110Tool Search는 MCP 컨텍스트 사용량을 낮게 유지하여 도구 정의를 Claude가 필요할 때까지 연기합니다. 세션 시작 시 도구 이름만 로드되므로 더 많은 MCP 서버를 추가해도 컨텍스트 윈도우에 미치는 영향이 최소화됩니다.

1111 

1112### 작동 방식

1113 

1114Tool Search는 기본적으로 활성화됩니다. MCP 도구는 미리 로드되지 않고 연기되며, Claude는 검색 도구를 사용하여 작업에 필요할 때 관련 도구를 검색합니다. Claude가 실제로 사용하는 도구만 컨텍스트에 들어갑니다. 사용자 관점에서 MCP 도구는 이전과 정확히 동일하게 작동합니다.

1115 

1116임계값 기반 로딩을 선호하는 경우 `ENABLE_TOOL_SEARCH=auto`를 설정하여 컨텍스트 윈도우의 10% 이내에 맞을 때 스키마를 미리 로드하고 오버플로우만 연기합니다. 모든 옵션은 [Tool Search 구성](#configure-tool-search)을 참조하세요.

1117 

1118### MCP 서버 작성자용

1119 

1120MCP 서버를 구축하는 경우 Tool Search가 활성화되면 서버 지침 필드가 더 유용해집니다. 서버 지침은 Claude가 [skills](/ko/skills)의 작동 방식과 유사하게 도구를 검색할 시기를 이해하는 데 도움이 됩니다.

1121 

1122다음을 설명하는 명확하고 설명적인 서버 지침을 추가합니다:

1123 

1124* 도구가 처리하는 작업의 범주

1125* Claude가 도구를 검색해야 할 때

1126* 서버가 제공하는 주요 기능

1127 

1128Claude Code는 도구 설명 및 서버 지침을 각각 2KB에서 자릅니다. 자르기를 피하려면 간결하게 유지하고 중요한 세부 정보를 시작 부분에 배치합니다.

1129 

1130### Tool Search 구성

1131 

1132Tool Search는 기본적으로 활성화됩니다: MCP 도구는 연기되고 필요에 따라 검색됩니다. Vertex AI에서는 기본적으로 비활성화되어 있습니다(도구 검색 베타 헤더를 허용하지 않음). `ANTHROPIC_BASE_URL`이 비 자사 호스트를 가리킬 때도 비활성화됩니다(대부분의 프록시가 `tool_reference` 블록을 전달하지 않기 때문). 명시적으로 `ENABLE_TOOL_SEARCH`를 설정하여 옵트인합니다. 이 기능은 `tool_reference` 블록을 지원하는 모델이 필요합니다: Sonnet 4 이상 또는 Opus 4 이상. Haiku 모델은 Tool Search를 지원하지 않습니다.

1133 

1134`ENABLE_TOOL_SEARCH` 환경 변수로 Tool Search 동작을 제어합니다:

1135 

1136| 값 | 동작 |

1137| :--------- | :----------------------------------------------------------------------------------- |

1138| (설정되지 않음) | 모든 MCP 도구 연기되고 필요에 따라 로드됨. Vertex AI 또는 `ANTHROPIC_BASE_URL`이 비 자사 호스트일 때 미리 로드로 돌아감 |

1139| `true` | 모든 MCP 도구 연기, Vertex AI 및 비 자사 `ANTHROPIC_BASE_URL` 포함 |

1140| `auto` | 임계값 모드: 도구가 컨텍스트 윈도우의 10% 이내에 맞으면 미리 로드, 그렇지 않으면 연기 |

1141| `auto:<N>` | 사용자 정의 백분율을 사용한 임계값 모드, `<N>`은 0-100 (예: `auto:5`는 5%) |

1142| `false` | 모든 MCP 도구 미리 로드, 연기 없음 |

1143 

1144```bash theme={null}

1145# 사용자 정의 5% 임계값 사용

1146ENABLE_TOOL_SEARCH=auto:5 claude

1147 

1148# Tool Search 완전히 비활성화

1149ENABLE_TOOL_SEARCH=false claude

1150```

1151 

1152또는 [settings.json `env` 필드](/ko/settings#available-settings)에서 값을 설정합니다.

1153 

1154`ToolSearch` 도구를 특별히 비활성화할 수도 있습니다:

1155 

1156```json theme={null}

1157{

1158 "permissions": {

1159 "deny": ["ToolSearch"]

1160 }

1161}

1162```

1163 

1164### 서버를 연기에서 제외

1165 

1166서버의 도구가 검색 단계 없이 항상 Claude에게 표시되어야 하는 경우 해당 서버의 구성에서 `alwaysLoad`를 `true`로 설정합니다. 그러면 `ENABLE_TOOL_SEARCH` 설정에 관계없이 해당 서버의 모든 도구가 세션 시작 시 컨텍스트에 로드됩니다. 매 턴마다 Claude가 필요로 하는 소수의 도구에 이를 사용합니다. 각 미리 로드된 도구는 대화에 사용할 수 있는 컨텍스트를 소비하기 때문입니다.

1167 

1168다음 `.mcp.json` 항목은 한 HTTP 서버를 제외하면서 다른 서버는 연기된 상태로 유지합니다:

1169 

1170```json theme={null}

1171{

1172 "mcpServers": {

1173 "core-tools": {

1174 "type": "http",

1175 "url": "https://mcp.example.com/mcp",

1176 "alwaysLoad": true

1177 }

1178 }

1179}

1180```

1181 

1182`alwaysLoad` 필드는 모든 서버 유형에서 사용 가능하며 Claude Code v2.1.121 이상이 필요합니다. MCP 서버는 도구의 `_meta` 객체에 `"anthropic/alwaysLoad": true`를 포함하여 개별 도구를 항상 로드되도록 표시할 수도 있으며, 이는 해당 도구에만 동일한 효과를 갖습니다.

1183 

1184## MCP 프롬프트를 명령으로 사용

1185 

1186MCP 서버는 Claude Code에서 명령으로 사용 가능하게 되는 프롬프트를 노출할 수 있습니다.

1187 

1188### MCP 프롬프트 실행

1189 

1190<Steps>

1191 <Step title="사용 가능한 프롬프트 검색">

1192 `/`를 입력하여 MCP 서버의 프롬프트를 포함한 모든 사용 가능한 명령을 확인합니다. MCP 프롬프트는 `/mcp__servername__promptname` 형식으로 나타납니다.

1193 </Step>

1194 

1195 <Step title="인수 없이 프롬프트 실행">

1196 ```text theme={null}

1197 /mcp__github__list_prs

1198 ```

1199 </Step>

1200 

1201 <Step title="인수를 사용하여 프롬프트 실행">

1202 많은 프롬프트는 인수를 허용합니다. 명령 뒤에 공백으로 구분하여 전달합니다:

1203 

1204 ```text theme={null}

1205 /mcp__github__pr_review 456

1206 ```

1207 

1208 ```text theme={null}

1209 /mcp__jira__create_issue "로그인 흐름의 버그" high

1210 ```

1211 </Step>

1212</Steps>

1213 

1214<Tip>

1215 팁:

1216 

1217 * MCP 프롬프트는 연결된 서버에서 동적으로 검색됩니다

1218 * 인수는 프롬프트의 정의된 매개변수를 기반으로 구문 분석됩니다

1219 * 프롬프트 결과는 대화에 직접 주입됩니다

1220 * 서버 및 프롬프트 이름은 정규화됩니다 (공백은 밑줄이 됨)

1221</Tip>

1222 

1223## 관리되는 MCP 구성

1224 

1225MCP 서버에 대한 중앙 집중식 제어가 필요한 조직의 경우 Claude Code는 두 가지 구성 옵션을 지원합니다:

1226 

12271. **`managed-mcp.json`을 사용한 독점 제어**: 사용자가 수정하거나 확장할 수 없는 고정된 MCP 서버 세트 배포

12282. **허용 목록/거부 목록을 사용한 정책 기반 제어**: 사용자가 자신의 서버를 추가할 수 있지만 허용되는 서버를 제한

1229 

1230이러한 옵션을 통해 IT 관리자는 다음을 수행할 수 있습니다:

1231 

1232* **직원이 액세스할 수 있는 MCP 서버 제어**: 조직 전체에 표준화된 승인된 MCP 서버 세트 배포

1233* **승인되지 않은 MCP 서버 방지**: 사용자가 승인되지 않은 MCP 서버를 추가하지 못하도록 제한

1234* **MCP 완전히 비활성화**: 필요한 경우 MCP 기능을 완전히 제거

1235 

1236### 옵션 1: managed-mcp.json을 사용한 독점 제어

1237 

1238`managed-mcp.json` 파일을 배포하면 모든 MCP 서버에 대한 **독점 제어**를 갖습니다. 사용자는 이 파일에 정의된 서버 이외의 MCP 서버를 추가, 수정 또는 사용할 수 없습니다. 이는 완전한 제어를 원하는 조직에 가장 간단한 방법입니다.

1239 

1240시스템 관리자는 구성 파일을 시스템 전체 디렉토리에 배포합니다:

1241 

1242* macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`

1243* Linux 및 WSL: `/etc/claude-code/managed-mcp.json`

1244* Windows: `C:\Program Files\ClaudeCode\managed-mcp.json`

1245 

1246<Note>

1247 이는 시스템 전체 경로입니다 (`~/Library/...`와 같은 사용자 홈 디렉토리가 아님). IT 관리자가 배포하기 위해 관리자 권한이 필요합니다.

1248</Note>

1249 

1250`managed-mcp.json` 파일은 표준 `.mcp.json` 파일과 동일한 형식을 사용합니다:

1251 

1252```json theme={null}

1253{

1254 "mcpServers": {

1255 "github": {

1256 "type": "http",

1257 "url": "https://api.githubcopilot.com/mcp/"

1258 },

1259 "sentry": {

1260 "type": "http",

1261 "url": "https://mcp.sentry.dev/mcp"

1262 },

1263 "company-internal": {

1264 "type": "stdio",

1265 "command": "/usr/local/bin/company-mcp-server",

1266 "args": ["--config", "/etc/company/mcp-config.json"],

1267 "env": {

1268 "COMPANY_API_URL": "https://internal.company.com"

1269 }

1270 }

1271 }

1272}

1273```

1274 

1275### 옵션 2: 허용 목록 및 거부 목록을 사용한 정책 기반 제어

1276 

1277독점 제어를 하는 대신 관리자는 사용자가 자신의 MCP 서버를 구성할 수 있도록 허용하면서 허용되는 서버에 제한을 적용할 수 있습니다. 이 방법은 [관리되는 설정 파일](/ko/settings#settings-files)의 `allowedMcpServers` 및 `deniedMcpServers`를 사용합니다.

1278 

1279<Note>

1280 **옵션 선택**: 사용자 사용자 정의 없이 고정된 서버 세트를 배포하려면 옵션 1 (`managed-mcp.json`)을 사용합니다. 사용자가 정책 제약 내에서 자신의 서버를 추가할 수 있도록 하려면 옵션 2 (허용 목록/거부 목록)를 사용합니다.

1281</Note>

1282 

1283#### 제한 옵션

1284 

1285허용 목록 또는 거부 목록의 각 항목은 세 가지 방식으로 서버를 제한할 수 있습니다:

1286 

12871. **서버 이름으로** (`serverName`): 서버의 구성된 이름과 일치

12882. **명령으로** (`serverCommand`): stdio 서버를 시작하는 데 사용되는 정확한 명령 및 인수와 일치

12893. **URL 패턴으로** (`serverUrl`): 와일드카드 지원을 사용하여 원격 서버 URL과 일치

1290 

1291**중요**: 각 항목은 `serverName`, `serverCommand` 또는 `serverUrl` 중 정확히 하나를 가져야 합니다.

1292 

1293#### 구성 예

1294 

1295```json theme={null}

1296{

1297 "allowedMcpServers": [

1298 // 서버 이름으로 허용

1299 { "serverName": "github" },

1300 { "serverName": "sentry" },

1301 

1302 // 정확한 명령으로 허용 (stdio 서버의 경우)

1303 { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },

1304 { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

1305 

1306 // URL 패턴으로 허용 (원격 서버의 경우)

1307 { "serverUrl": "https://mcp.company.com/*" },

1308 { "serverUrl": "https://*.internal.corp/*" }

1309 ],

1310 "deniedMcpServers": [

1311 // 서버 이름으로 차단

1312 { "serverName": "dangerous-server" },

1313 

1314 // 정확한 명령으로 차단 (stdio 서버의 경우)

1315 { "serverCommand": ["npx", "-y", "unapproved-package"] },

1316 

1317 // URL 패턴으로 차단 (원격 서버의 경우)

1318 { "serverUrl": "https://*.untrusted.com/*" }

1319 ]

1320}

1321```

1322 

1323#### 명령 기반 제한의 작동 방식

1324 

1325**정확한 일치**:

1326 

1327* 명령 배열은 **정확히** 일치해야 합니다 - 명령과 올바른 순서의 모든 인수

1328* 예: `["npx", "-y", "server"]`는 `["npx", "server"]` 또는 `["npx", "-y", "server", "--flag"]`와 일치하지 않습니다

1329 

1330**Stdio 서버 동작**:

1331 

1332* 허용 목록에 **모든** `serverCommand` 항목이 포함되면 stdio 서버는 해당 명령 중 하나와 일치해야 합니다

1333* Stdio 서버는 명령 제한이 있을 때 이름만으로는 통과할 수 없습니다

1334* 이는 관리자가 실행할 수 있는 명령을 적용할 수 있도록 합니다

1335 

1336**비 stdio 서버 동작**:

1337 

1338* 원격 서버 (HTTP, SSE, WebSocket)는 허용 목록에 `serverUrl` 항목이 있을 때 URL 기반 일치를 사용합니다

1339* URL 항목이 없으면 원격 서버는 이름 기반 일치로 돌아갑니다

1340* 명령 제한은 원격 서버에 적용되지 않습니다

1341 

1342#### URL 기반 제한의 작동 방식

1343 

1344URL 패턴은 `*`를 사용하여 와일드카드를 지원하여 모든 문자 시퀀스와 일치합니다. 이는 전체 도메인 또는 하위 도메인을 허용하는 데 유용합니다.

1345 

1346**와일드카드 예**:

1347 

1348* `https://mcp.company.com/*` - 특정 도메인의 모든 경로 허용

1349* `https://*.example.com/*` - example.com의 모든 하위 도메인 허용

1350* `http://localhost:*/*` - localhost의 모든 포트 허용

1351 

1352**원격 서버 동작**:

1353 

1354* 허용 목록에 **모든** `serverUrl` 항목이 포함되면 원격 서버는 해당 URL 패턴 중 하나와 일치해야 합니다

1355* 원격 서버는 URL 제한이 있을 때 이름만으로는 통과할 수 없습니다

1356* 이는 관리자가 허용되는 원격 엔드포인트를 적용할 수 있도록 합니다

1357 

1358<Accordion title="예: URL 전용 허용 목록">

1359 ```json theme={null}

1360 {

1361 "allowedMcpServers": [

1362 { "serverUrl": "https://mcp.company.com/*" },

1363 { "serverUrl": "https://*.internal.corp/*" }

1364 ]

1365 }

1366 ```

1367 

1368 **결과**:

1369 

1370 * `https://mcp.company.com/api`의 HTTP 서버: ✅ 허용됨 (URL 패턴과 일치)

1371 * `https://api.internal.corp/mcp`의 HTTP 서버: ✅ 허용됨 (와일드카드 하위 도메인과 일치)

1372 * `https://external.com/mcp`의 HTTP 서버: ❌ 차단됨 (URL 패턴과 일치하지 않음)

1373 * 모든 명령의 Stdio 서버: ❌ 차단됨 (일치할 이름 또는 명령 항목 없음)

1374</Accordion>

1375 

1376<Accordion title="예: 명령 전용 허용 목록">

1377 ```json theme={null}

1378 {

1379 "allowedMcpServers": [

1380 { "serverCommand": ["npx", "-y", "approved-package"] }

1381 ]

1382 }

1383 ```

1384 

1385 **결과**:

1386 

1387 * `["npx", "-y", "approved-package"]`를 사용한 Stdio 서버: ✅ 허용됨 (명령과 일치)

1388 * `["node", "server.js"]`를 사용한 Stdio 서버: ❌ 차단됨 (명령과 일치하지 않음)

1389 * "my-api"라는 이름의 HTTP 서버: ❌ 차단됨 (일치할 이름 항목 없음)

1390</Accordion>

1391 

1392<Accordion title="예: 혼합 이름 및 명령 허용 목록">

1393 ```json theme={null}

1394 {

1395 "allowedMcpServers": [

1396 { "serverName": "github" },

1397 { "serverCommand": ["npx", "-y", "approved-package"] }

1398 ]

1399 }

1400 ```

1401 

1402 **결과**:

1403 

1404 * `["npx", "-y", "approved-package"]`를 사용한 "local-tool"이라는 Stdio 서버: ✅ 허용됨 (명령과 일치)

1405 * `["node", "server.js"]`를 사용한 "local-tool"이라는 Stdio 서버: ❌ 차단됨 (명령 항목이 있지만 일치하지 않음)

1406 * `["node", "server.js"]`를 사용한 "github"라는 Stdio 서버: ❌ 차단됨 (명령 항목이 있을 때 stdio 서버는 명령과 일치해야 함)

1407 * "github"라는 이름의 HTTP 서버: ✅ 허용됨 (이름과 일치)

1408 * "other-api"라는 이름의 HTTP 서버: ❌ 차단됨 (이름과 일치하지 않음)

1409</Accordion>

1410 

1411<Accordion title="예: 이름 전용 허용 목록">

1412 ```json theme={null}

1413 {

1414 "allowedMcpServers": [

1415 { "serverName": "github" },

1416 { "serverName": "internal-tool" }

1417 ]

1418 }

1419 ```

1420 

1421 **결과**:

1422 

1423 * 모든 명령을 사용한 "github"라는 Stdio 서버: ✅ 허용됨 (명령 제한 없음)

1424 * 모든 명령을 사용한 "internal-tool"이라는 Stdio 서버: ✅ 허용됨 (명령 제한 없음)

1425 * "github"라는 이름의 HTTP 서버: ✅ 허용됨 (이름과 일치)

1426 * "other"라는 이름의 모든 서버: ❌ 차단됨 (이름과 일치하지 않음)

1427</Accordion>

1428 

1429#### 허용 목록 동작 (`allowedMcpServers`)

1430 

1431* `undefined` (기본값): 제한 없음 - 사용자는 모든 MCP 서버를 구성할 수 있습니다

1432* 빈 배열 `[]`: 완전한 잠금 - 사용자는 MCP 서버를 구성할 수 없습니다

1433* 항목 목록: 사용자는 이름, 명령 또는 URL 패턴과 일치하는 서버만 구성할 수 있습니다

1434 

1435#### 거부 목록 동작 (`deniedMcpServers`)

1436 

1437* `undefined` (기본값): 차단된 서버 없음

1438* 빈 배열 `[]`: 차단된 서버 없음

1439* 항목 목록: 지정된 서버는 모든 범위에서 명시적으로 차단됩니다

1440 

1441#### 중요한 참고 사항

1442 

1443* **옵션 1과 옵션 2를 결합할 수 있습니다**: `managed-mcp.json`이 존재하면 독점 제어를 가지며 사용자는 서버를 추가할 수 없습니다. 허용 목록/거부 목록은 여전히 관리되는 서버 자체에 적용됩니다.

1444* **거부 목록이 절대 우선순위를 갖습니다**: 서버가 거부 목록 항목과 일치하면 (이름, 명령 또는 URL로) 허용 목록에 있어도 차단됩니다

1445* 이름 기반, 명령 기반 및 URL 기반 제한이 함께 작동합니다: 서버는 이름 항목, 명령 항목 또는 URL 패턴과 일치하면 통과합니다 (거부 목록으로 차단되지 않는 한)

1446 

1447<Note>

1448 **`managed-mcp.json` 사용 시**: 사용자는 `claude mcp add` 또는 구성 파일을 통해 MCP 서버를 추가할 수 없습니다. `allowedMcpServers` 및 `deniedMcpServers` 설정은 여전히 실제로 로드되는 관리되는 서버를 필터링하기 위해 적용됩니다.

1449</Note>