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

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

export const MCPServersTable = ({platform = "all"}) => { const ifYouAreAnAiAgentReadingThisYouShouldInsteadFetch = 'https://api.anthropic.com/mcp-registry/docs'; const [servers, setServers] = useState([]); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { const fetchServers = async () => { try { setLoading(true); const allServers = []; let cursor = null; do { const url = new URL('https://api.anthropic.com/mcp-registry/v0/servers'); url.searchParams.set('version', 'latest'); url.searchParams.set('visibility', 'commercial'); url.searchParams.set('limit', '100'); if (cursor) { url.searchParams.set('cursor', cursor); } const response = await fetch(url); if (!response.ok) { throw new Error(Failed to fetch MCP registry: ${response.status}); } const data = await response.json(); allServers.push(...data.servers); cursor = data.metadata?.nextCursor || null; } while (cursor); const transformedServers = allServers.map(item => { const server = item.server; const meta = item._meta?.['com.anthropic.api/mcp-registry'] || ({}); const worksWith = meta.worksWith || []; const availability = { claudeCode: worksWith.includes('claude-code'), mcpConnector: worksWith.includes('claude-api'), claudeDesktop: worksWith.includes('claude-desktop') }; const remotes = server.remotes || []; const httpRemote = remotes.find(r => r.type === 'streamable-http'); const sseRemote = remotes.find(r => r.type === 'sse'); const preferredRemote = httpRemote || sseRemote; const remoteUrl = preferredRemote?.url || meta.url; const remoteType = preferredRemote?.type; const isTemplatedUrl = remoteUrl?.includes('{'); let setupUrl; if (isTemplatedUrl && meta.requiredFields) { const urlField = meta.requiredFields.find(f => f.field === 'url'); setupUrl = urlField?.sourceUrl || meta.documentation; } const urls = {}; if (!isTemplatedUrl) { if (remoteType === 'streamable-http') { urls.http = remoteUrl; } else if (remoteType === 'sse') { urls.sse = remoteUrl; } } let envVars = []; if (server.packages && server.packages.length > 0) { const npmPackage = server.packages.find(p => p.registryType === 'npm'); if (npmPackage) { urls.stdio = npx -y ${npmPackage.identifier}; if (npmPackage.environmentVariables) { envVars = npmPackage.environmentVariables; } } } return { name: meta.displayName || server.title || server.name, description: meta.oneLiner || server.description, documentation: meta.documentation, urls: urls, envVars: envVars, availability: availability, customCommands: meta.claudeCodeCopyText ? { claudeCode: meta.claudeCodeCopyText } : undefined, setupUrl: setupUrl }; }); setServers(transformedServers); setError(null); } catch (err) { setError(err.message); console.error('Error fetching MCP registry:', err); } finally { setLoading(false); } }; fetchServers(); }, []); const generateClaudeCodeCommand = server => { if (server.customCommands && server.customCommands.claudeCode) { return server.customCommands.claudeCode.replace('--transport streamable-http', '--transport http'); } const serverSlug = server.name.toLowerCase().replace(/[^a-z0-9]/g, '-'); if (server.urls.http) { return claude mcp add ${serverSlug} --transport http ${server.urls.http}; } if (server.urls.sse) { return claude mcp add ${serverSlug} --transport sse ${server.urls.sse}; } if (server.urls.stdio) { const envFlags = server.envVars && server.envVars.length > 0 ? server.envVars.map(v => --env ${v.name}=YOUR_${v.name}).join(' ') : ''; const baseCommand = claude mcp add ${serverSlug} --transport stdio; return envFlags ? ${baseCommand} ${envFlags} -- ${server.urls.stdio} : ${baseCommand} -- ${server.urls.stdio}; } return null; }; if (loading) { return

Loading MCP servers...

; } if (error) { return

Error loading MCP servers: {error}

; } const filteredServers = servers.filter(server => { if (platform === "claudeCode") { return server.availability.claudeCode; } else if (platform === "mcpConnector") { return server.availability.mcpConnector; } else if (platform === "claudeDesktop") { return server.availability.claudeDesktop; } else if (platform === "all") { return true; } else { throw new Error(Unknown platform: ${platform}); } }); return <>

  <div className="cards-container">
    {filteredServers.map(server => {
const claudeCodeCommand = generateClaudeCodeCommand(server);
const mcpUrl = server.urls.http || server.urls.sse;
const commandToShow = platform === "claudeCode" ? claudeCodeCommand : mcpUrl;
return <div key={server.name} className="server-card">
          <div>
            {server.documentation ? <a href={server.documentation}>
                <strong>{server.name}</strong>
              </a> : <strong>{server.name}</strong>}
          </div>

          <p style={{
  margin: '0.5rem 0',
  fontSize: '0.9rem'
}}>
            {server.description}
          </p>

          {server.setupUrl && <p style={{
  margin: '0.25rem 0',
  fontSize: '0.8rem',
  fontStyle: 'italic',
  opacity: 0.7
}}>
              Requires user-specific URL.{' '}
              <a href={server.setupUrl} style={{
  textDecoration: 'underline'
}}>
                Get your URL here
              </a>.
            </p>}

          {commandToShow && !server.setupUrl && <>
            <p style={{
  display: 'block',
  fontSize: '0.75rem',
  fontWeight: 500,
  minWidth: 'fit-content',
  marginTop: '0.5rem',
  marginBottom: 0
}}>
              {platform === "claudeCode" ? "Command" : "URL"}
            </p>
            <div className="command-row">
              <code>
                {commandToShow}
              </code>
            </div>
          </>}
        </div>;

})}

</>; };

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

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

MCP로 할 수 있는 것

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

이슈 추적기에서 기능 구현: "JIRA 이슈 ENG-4521에 설명된 기능을 추가하고 GitHub에서 PR을 생성하세요."
모니터링 데이터 분석: "Sentry와 Statsig을 확인하여 ENG-4521에 설명된 기능의 사용량을 확인하세요."
데이터베이스 쿼리: "PostgreSQL 데이터베이스를 기반으로 기능 ENG-4521을 사용한 무작위 사용자 10명의 이메일을 찾으세요."
디자인 통합: "Slack에 게시된 새로운 Figma 디자인을 기반으로 표준 이메일 템플릿을 업데이트하세요."
워크플로우 자동화: "이 10명의 사용자를 새로운 기능에 대한 피드백 세션에 초대하는 Gmail 초안을 생성하세요."
외부 이벤트에 반응: MCP 서버는 채널로도 작동할 수 있으며, 세션에 메시지를 푸시하므로 Claude는 자리를 비운 동안 Telegram 메시지, Discord 채팅 또는 webhook 이벤트에 반응할 수 있습니다.

MCP 서버 설치

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

옵션 1: 원격 HTTP 서버 추가

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

# 기본 구문
claude mcp add --transport http <name> <url>

# 실제 예: Notion에 연결
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Bearer 토큰을 사용한 예
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

옵션 2: 원격 SSE 서버 추가

# 기본 구문
claude mcp add --transport sse <name> <url>

# 실제 예: Asana에 연결
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 인증 헤더를 사용한 예
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

옵션 3: 로컬 stdio 서버 추가

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

# 기본 구문
claude mcp add [options] <name> -- <command> [args...]

# 실제 예: Airtable 서버 추가
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

서버 관리

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

# 구성된 모든 서버 나열
claude mcp list

# 특정 서버의 세부 정보 가져오기
claude mcp get github

# 서버 제거
claude mcp remove github

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

/mcp 패널은 각 연결된 서버 옆에 도구 개수를 표시하고 도구 기능을 광고하지만 도구를 노출하지 않는 서버에 플래그를 지정합니다.

서버 이름 workspace는 내부 사용을 위해 예약되어 있습니다. 구성에서 해당 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다.

동적 도구 업데이트

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

자동 재연결

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

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

채널을 사용한 메시지 푸시

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

Tip

팁:

--scope 플래그를 사용하여 구성이 저장되는 위치를 지정하세요:
local (기본값): 현재 프로젝트에서만 사용자에게만 사용 가능 (이전 버전에서는 project라고 불렸음)
project: .mcp.json 파일을 통해 프로젝트의 모든 사람과 공유
user: 모든 프로젝트에서 사용자에게 사용 가능 (이전 버전에서는 global이라고 불렸음)
--env 플래그로 환경 변수를 설정하세요 (예: --env KEY=value)
MCP_TIMEOUT 환경 변수를 사용하여 MCP 서버 시작 시간 초과를 구성하세요 (예: MCP_TIMEOUT=10000 claude는 10초 시간 초과를 설정)
Claude Code는 MCP 도구 출력이 10,000 토큰을 초과할 때 경고를 표시합니다. 이 제한을 늘리려면 MAX_MCP_OUTPUT_TOKENS 환경 변수를 설정하세요 (예: MAX_MCP_OUTPUT_TOKENS=50000)
OAuth 2.0 인증이 필요한 원격 서버로 인증하려면 /mcp를 사용하세요

플러그인 제공 MCP 서버

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

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

플러그인은 플러그인 루트의 .mcp.json 또는 plugin.json에 인라인으로 MCP 서버를 정의합니다
플러그인이 활성화되면 MCP 서버가 자동으로 시작됩니다
플러그인 MCP 도구는 수동으로 구성된 MCP 도구와 함께 나타납니다
플러그인 서버는 플러그인 설치를 통해 관리됩니다 (/mcp 명령이 아님)

플러그인 MCP 구성 예:

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

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

또는 plugin.json에 인라인:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

플러그인 MCP 기능:

자동 라이프사이클: 세션 시작 시 활성화된 플러그인의 서버가 자동으로 연결됩니다. 세션 중에 플러그인을 활성화하거나 비활성화하면 /reload-plugins를 실행하여 MCP 서버를 연결하거나 연결 해제합니다
환경 변수: 번들된 플러그인 파일에 ${CLAUDE_PLUGIN_ROOT} 사용 및 플러그인 업데이트를 유지하는 지속적인 상태에 ${CLAUDE_PLUGIN_DATA} 사용
사용자 환경 액세스: 수동으로 구성된 서버와 동일한 환경 변수에 액세스
여러 전송 유형: stdio, SSE 및 HTTP 전송 지원 (전송 지원은 서버에 따라 다를 수 있음)

플러그인 MCP 서버 보기:

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

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

플러그인 MCP 서버의 이점:

번들 배포: 도구 및 서버가 함께 패키징됨
자동 설정: 수동 MCP 구성이 필요 없음
팀 일관성: 플러그인이 설치되면 모든 사람이 동일한 도구를 얻음

플러그인과 함께 MCP 서버를 번들로 제공하는 방법에 대한 자세한 내용은 플러그인 구성 요소 참조를 참조하세요.

MCP 설치 범위

MCP 서버는 세 가지 범위에서 구성할 수 있습니다. 선택한 범위는 서버가 로드되는 프로젝트와 구성이 팀과 공유되는지 여부를 제어합니다. 관리자는 관리형 구성을 통해 엔터프라이즈 수준에서 서버를 배포할 수도 있습니다.

범위	로드 위치	팀과 공유	저장 위치
로컬	현재 프로젝트만	아니오	`~/.claude.json`
프로젝트	현재 프로젝트만	예, 버전 제어를 통해	프로젝트 루트의 `.mcp.json`
사용자	모든 프로젝트	아니오	`~/.claude.json`

로컬 범위

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

# 로컬 범위 서버 추가 (기본값)
claude mcp add --transport http stripe https://mcp.stripe.com

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

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

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

프로젝트 범위

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

# 프로젝트 범위 서버 추가
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

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

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

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

사용자 범위

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

# 사용자 서버 추가
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

범위 계층 및 우선순위

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

로컬 범위
프로젝트 범위
사용자 범위
플러그인 제공 서버
Claude.ai 커넥터

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

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

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

지원되는 구문:

${VAR} - 환경 변수 VAR의 값으로 확장
${VAR:-default} - VAR이 설정되면 확장, 그렇지 않으면 default 사용

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

command - 서버 실행 파일 경로
args - 명령줄 인수
env - 서버에 전달되는 환경 변수
url - HTTP 서버 유형의 경우
headers - HTTP 서버 인증의 경우

변수 확장을 사용한 예:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

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

실제 예

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

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

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

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

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

검색 기능이 결과를 반환하는지 확인
``` */}

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

```bash theme={null}
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Sentry 계정으로 인증합니다:

/mcp

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

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

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

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

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

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

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

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

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

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

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

예: PostgreSQL 데이터베이스 쿼리

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

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

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

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

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

원격 MCP 서버로 인증

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

인증이 필요한 서버 추가

예를 들어:

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

Claude Code 내에서 /mcp 명령 사용

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

/mcp

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

고정 OAuth 콜백 포트 사용

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

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

# 동적 클라이언트 등록을 사용한 고정 콜백 포트
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

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

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

서버로 OAuth 앱 등록

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

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

자격 증명으로 서버 추가

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

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

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

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

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

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

claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

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

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

Claude Code에서 인증

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

OAuth 메타데이터 검색 재정의

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

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

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

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

OAuth 범위 제한

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

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

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

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

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

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

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

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

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

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

요구 사항:

명령은 JSON 객체의 문자열 키-값 쌍을 stdout에 작성해야 합니다
명령은 10초 시간 초과를 사용하여 셸에서 실행됩니다
동적 헤더는 동일한 이름의 정적 headers를 재정의합니다

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

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

변수	값
`CLAUDE_CODE_MCP_SERVER_NAME`	MCP 서버의 이름
`CLAUDE_CODE_MCP_SERVER_URL`	MCP 서버의 URL

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

JSON 구성에서 MCP 서버 추가

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

JSON에서 MCP 서버 추가

# 기본 구문
claude mcp add-json <name> '<json>'

# 예: JSON 구성으로 HTTP 서버 추가
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# 예: JSON 구성으로 stdio 서버 추가
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# 예: 사전 구성된 OAuth 자격 증명으로 HTTP 서버 추가
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

서버가 추가되었는지 확인

claude mcp get weather-api

Claude Desktop에서 MCP 서버 가져오기

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

Claude Desktop에서 서버 가져오기

# 기본 구문 
claude mcp add-from-claude-desktop

가져올 서버 선택

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

서버가 가져와졌는지 확인

claude mcp list

Claude.ai에서 MCP 서버 사용

Claude.ai 계정으로 Claude Code에 로그인한 경우 Claude.ai에서 추가한 MCP 서버는 Claude Code에서 자동으로 사용 가능합니다:

Claude.ai에서 MCP 서버 구성

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

MCP 서버 인증

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

Claude Code에서 서버 보기 및 관리

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

/mcp

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

Claude Code에서 추가한 서버는 동일한 URL을 가리키는 claude.ai 커넥터보다 우선순위를 갖습니다. 이 경우 /mcp는 커넥터를 숨김으로 표시하고 커넥터를 사용하려는 경우 중복을 제거하는 방법을 표시합니다.

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

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Claude Code를 MCP 서버로 사용

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

# Claude를 stdio MCP 서버로 시작
claude mcp serve

claude_desktop_config.json에 이 구성을 추가하여 Claude Desktop에서 사용할 수 있습니다:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Warning

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

전체 경로를 찾으려면:

which claude

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

{
"mcpServers": {
"claude-code": {
"type": "stdio",
"command": "/full/path/to/claude",
"args": ["mcp", "serve"],
"env": {}
}
}
}

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

MCP 출력 제한 및 경고

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

출력 경고 임계값: Claude Code는 MCP 도구 출력이 10,000 토큰을 초과할 때 경고를 표시합니다
구성 가능한 제한: MAX_MCP_OUTPUT_TOKENS 환경 변수를 사용하여 최대 허용 MCP 출력 토큰을 조정할 수 있습니다
기본 제한: 기본 최대값은 25,000 토큰입니다
범위: 환경 변수는 자신의 제한을 선언하지 않는 도구에 적용됩니다. anthropic/maxResultSizeChars를 설정하는 도구는 MAX_MCP_OUTPUT_TOKENS이 설정된 것과 관계없이 텍스트 콘텐츠에 대해 해당 값을 사용합니다. 이미지 데이터를 반환하는 도구는 여전히 MAX_MCP_OUTPUT_TOKENS의 영향을 받습니다

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

export MAX_MCP_OUTPUT_TOKENS=50000
claude

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

대규모 데이터 세트 또는 데이터베이스 쿼리
상세한 보고서 또는 문서 생성
광범위한 로그 파일 또는 디버깅 정보 처리

특정 도구의 제한 늘리기

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

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

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

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

MCP 리소스 요청에 응답

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

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

양식 모드: Claude Code는 서버에서 정의한 양식 필드가 있는 대화 상자를 표시합니다 (예: 사용자 이름 및 암호 프롬프트). 필드를 입력하고 제출합니다.
URL 모드: Claude Code는 인증 또는 승인을 위해 브라우저 URL을 엽니다. 브라우저에서 흐름을 완료한 다음 CLI에서 확인합니다.

리소스 요청에 자동으로 응답하려면 Elicitation 훅을 사용하세요.

리소스 요청을 사용하는 MCP 서버를 구축하는 경우 MCP 리소스 요청 사양에서 프로토콜 세부 정보 및 스키마 예를 참조하세요.

MCP 리소스 사용

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

MCP 리소스 참조

사용 가능한 리소스 나열

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

특정 리소스 참조

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

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

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

여러 리소스 참조

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

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

MCP Tool Search로 확장

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

작동 방식

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

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

MCP 서버 작성자용

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

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

도구가 처리하는 작업의 범주
Claude가 도구를 검색해야 할 때
서버가 제공하는 주요 기능

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

Tool Search 구성

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

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

값	동작
(설정되지 않음)	모든 MCP 도구 연기되고 필요에 따라 로드됨. Vertex AI 또는 `ANTHROPIC_BASE_URL`이 비 자사 호스트일 때 미리 로드로 돌아감
`true`	모든 MCP 도구 연기, Vertex AI 및 비 자사 `ANTHROPIC_BASE_URL` 포함
`auto`	임계값 모드: 도구가 컨텍스트 윈도우의 10% 이내에 맞으면 미리 로드, 그렇지 않으면 연기
`auto:<N>`	사용자 정의 백분율을 사용한 임계값 모드, `<N>`은 0-100 (예: `auto:5`는 5%)
`false`	모든 MCP 도구 미리 로드, 연기 없음

# 사용자 정의 5% 임계값 사용
ENABLE_TOOL_SEARCH=auto:5 claude

# Tool Search 완전히 비활성화
ENABLE_TOOL_SEARCH=false claude

또는 settings.json env 필드에서 값을 설정합니다.

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

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

서버를 연기에서 제외

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

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

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

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

alwaysLoad: true를 설정하면 서버가 연결될 때까지 시작이 차단되며, 표준 5초 연결 타임아웃으로 제한됩니다. 이는 MCP_CONNECTION_NONBLOCKING=1이 설정된 경우에도 적용됩니다. 첫 번째 프롬프트가 빌드될 때 도구가 있어야 하기 때문입니다. 비차단이 활성화된 경우 다른 서버는 여전히 백그라운드에서 연결됩니다.

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

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

MCP 프롬프트 실행

사용 가능한 프롬프트 검색

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

인수 없이 프롬프트 실행

/mcp__github__list_prs

인수를 사용하여 프롬프트 실행

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

/mcp__github__pr_review 456

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

관리되는 MCP 구성

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

managed-mcp.json을 사용한 독점 제어: 사용자가 수정하거나 확장할 수 없는 고정된 MCP 서버 세트 배포
허용 목록/거부 목록을 사용한 정책 기반 제어: 사용자가 자신의 서버를 추가할 수 있지만 허용되는 서버를 제한

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

직원이 액세스할 수 있는 MCP 서버 제어: 조직 전체에 표준화된 승인된 MCP 서버 세트 배포
승인되지 않은 MCP 서버 방지: 사용자가 승인되지 않은 MCP 서버를 추가하지 못하도록 제한
MCP 완전히 비활성화: 필요한 경우 MCP 기능을 완전히 제거

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

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

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

macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
Linux 및 WSL: /etc/claude-code/managed-mcp.json
Windows: C:\Program Files\ClaudeCode\managed-mcp.json

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

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

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

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

제한 옵션

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

서버 이름으로 (serverName): 서버의 구성된 이름과 일치
명령으로 (serverCommand): stdio 서버를 시작하는 데 사용되는 정확한 명령 및 인수와 일치
URL 패턴으로 (serverUrl): 와일드카드 지원을 사용하여 원격 서버 URL과 일치

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

구성 예

{
  "allowedMcpServers": [
    // 서버 이름으로 허용
    { "serverName": "github" },
    { "serverName": "sentry" },

    // 정확한 명령으로 허용 (stdio 서버의 경우)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // URL 패턴으로 허용 (원격 서버의 경우)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // 서버 이름으로 차단
    { "serverName": "dangerous-server" },

    // 정확한 명령으로 차단 (stdio 서버의 경우)
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // URL 패턴으로 차단 (원격 서버의 경우)
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

명령 기반 제한의 작동 방식

정확한 일치:

명령 배열은 정확히 일치해야 합니다 - 명령과 올바른 순서의 모든 인수
예: ["npx", "-y", "server"]는 ["npx", "server"] 또는 ["npx", "-y", "server", "--flag"]와 일치하지 않습니다

Stdio 서버 동작:

허용 목록에 모든 serverCommand 항목이 포함되면 stdio 서버는 해당 명령 중 하나와 일치해야 합니다
Stdio 서버는 명령 제한이 있을 때 이름만으로는 통과할 수 없습니다
이는 관리자가 실행할 수 있는 명령을 적용할 수 있도록 합니다

비 stdio 서버 동작:

원격 서버 (HTTP, SSE, WebSocket)는 허용 목록에 serverUrl 항목이 있을 때 URL 기반 일치를 사용합니다
URL 항목이 없으면 원격 서버는 이름 기반 일치로 돌아갑니다
명령 제한은 원격 서버에 적용되지 않습니다

URL 기반 제한의 작동 방식

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

와일드카드 예:

https://mcp.company.com/* - 특정 도메인의 모든 경로 허용
https://*.example.com/* - example.com의 모든 하위 도메인 허용
http://localhost:*/* - localhost의 모든 포트 허용

호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하여 DNS 의미론을 따릅니다. *://Mcp.Example.com/*와 같은 패턴은 https://mcp.example.com/api와 일치하며, https://mcp.example.com.은 https://mcp.example.com과 동일하게 처리됩니다. 스킴과 경로는 대소문자를 구분합니다.

원격 서버 동작:

허용 목록에 모든 serverUrl 항목이 포함되면 원격 서버는 해당 URL 패턴 중 하나와 일치해야 합니다
원격 서버는 URL 제한이 있을 때 이름만으로는 통과할 수 없습니다
이는 관리자가 허용되는 원격 엔드포인트를 적용할 수 있도록 합니다

예: URL 전용 허용 목록

{
"allowedMcpServers": [
{ "serverUrl": "https://mcp.company.com/*" },
{ "serverUrl": "https://*.internal.corp/*" }
]
}

결과:

https://mcp.company.com/api의 HTTP 서버: ✅ 허용됨 (URL 패턴과 일치)
https://api.internal.corp/mcp의 HTTP 서버: ✅ 허용됨 (와일드카드 하위 도메인과 일치)
https://external.com/mcp의 HTTP 서버: ❌ 차단됨 (URL 패턴과 일치하지 않음)
모든 명령의 Stdio 서버: ❌ 차단됨 (일치할 이름 또는 명령 항목 없음)

예: 명령 전용 허용 목록

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

결과:

["npx", "-y", "approved-package"]를 사용한 Stdio 서버: ✅ 허용됨 (명령과 일치)
["node", "server.js"]를 사용한 Stdio 서버: ❌ 차단됨 (명령과 일치하지 않음)
"my-api"라는 이름의 HTTP 서버: ❌ 차단됨 (일치할 이름 항목 없음)

예: 혼합 이름 및 명령 허용 목록

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

결과:

["npx", "-y", "approved-package"]를 사용한 "local-tool"이라는 Stdio 서버: ✅ 허용됨 (명령과 일치)
["node", "server.js"]를 사용한 "local-tool"이라는 Stdio 서버: ❌ 차단됨 (명령 항목이 있지만 일치하지 않음)
["node", "server.js"]를 사용한 "github"라는 Stdio 서버: ❌ 차단됨 (명령 항목이 있을 때 stdio 서버는 명령과 일치해야 함)
"github"라는 이름의 HTTP 서버: ✅ 허용됨 (이름과 일치)
"other-api"라는 이름의 HTTP 서버: ❌ 차단됨 (이름과 일치하지 않음)

예: 이름 전용 허용 목록

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverName": "internal-tool" }
]
}

결과:

모든 명령을 사용한 "github"라는 Stdio 서버: ✅ 허용됨 (명령 제한 없음)
모든 명령을 사용한 "internal-tool"이라는 Stdio 서버: ✅ 허용됨 (명령 제한 없음)
"github"라는 이름의 HTTP 서버: ✅ 허용됨 (이름과 일치)
"other"라는 이름의 모든 서버: ❌ 차단됨 (이름과 일치하지 않음)

허용 목록 동작 (`allowedMcpServers`)

undefined (기본값): 제한 없음 - 사용자는 모든 MCP 서버를 구성할 수 있습니다
빈 배열 []: 완전한 잠금 - 사용자는 MCP 서버를 구성할 수 없습니다
항목 목록: 사용자는 이름, 명령 또는 URL 패턴과 일치하는 서버만 구성할 수 있습니다

거부 목록 동작 (`deniedMcpServers`)

undefined (기본값): 차단된 서버 없음
빈 배열 []: 차단된 서버 없음
항목 목록: 지정된 서버는 모든 범위에서 명시적으로 차단됩니다

중요한 참고 사항

옵션 1과 옵션 2를 결합할 수 있습니다: managed-mcp.json이 존재하면 독점 제어를 가지며 사용자는 서버를 추가할 수 없습니다. 허용 목록/거부 목록은 여전히 관리되는 서버 자체에 적용됩니다.
거부 목록이 절대 우선순위를 갖습니다: 서버가 거부 목록 항목과 일치하면 (이름, 명령 또는 URL로) 허용 목록에 있어도 차단됩니다
이름 기반, 명령 기반 및 URL 기반 제한이 함께 작동합니다: 서버는 이름 항목, 명령 항목 또는 URL 패턴과 일치하면 통과합니다 (거부 목록으로 차단되지 않는 한)

mcp.md +12 −2

325/mcp325/mcp

326```326```

327 327

328`/mcp` 패널은 각 연결된 서버 옆에 도구 개수를 표시하고 도구 기능을 광고하지만 도구를 노출하지 않는 서버에 플래그를 지정합니다.

329

330서버 이름 `workspace`는 내부 사용을 위해 예약되어 있습니다. 구성에서 해당 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다.

331

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

329 333

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

421 425

422## MCP 설치 범위426## MCP 설치 범위

423 427

424MCP 서버는 세 가지 범위에서 구성할 수 있습니다. 선택한 범위는 서버가 로드되는 프로젝트와 구성이 팀과 공유되는지 여부를 제어합니다.428MCP 서버는 세 가지 범위에서 구성할 수 있습니다. 선택한 범위는 서버가 로드되는 프로젝트와 구성이 팀과 공유되는지 여부를 제어합니다. 관리자는 [관리형 구성](#managed-mcp-configuration)을 통해 엔터프라이즈 수준에서 서버를 배포할 수도 있습니다.

425 429

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

427| ---------------------- | -------- | ------------ | -------------------- |431| ---------------------- | -------- | ------------ | -------------------- |

498 502

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

500 504

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

502 506

5031. 로컬 범위5071. 로컬 범위

5042. 프로젝트 범위5082. 프로젝트 범위

942 </Step>946 </Step>

943</Steps>947</Steps>

944 948

949Claude Code에서 추가한 서버는 동일한 URL을 가리키는 claude.ai 커넥터보다 [우선순위](#scope-hierarchy-and-precedence)를 갖습니다. 이 경우 `/mcp`는 커넥터를 숨김으로 표시하고 커넥터를 사용하려는 경우 중복을 제거하는 방법을 표시합니다.

950

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

946 952

947```bash theme={null}953```bash theme={null}

1181 1187

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

1183 1189

1190`alwaysLoad: true`를 설정하면 서버가 연결될 때까지 시작이 차단되며, 표준 5초 연결 타임아웃으로 제한됩니다. 이는 [`MCP_CONNECTION_NONBLOCKING=1`](/ko/env-vars)이 설정된 경우에도 적용됩니다. 첫 번째 프롬프트가 빌드될 때 도구가 있어야 하기 때문입니다. 비차단이 활성화된 경우 다른 서버는 여전히 백그라운드에서 연결됩니다.

1191

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

1185 1193

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

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

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

1351 1359

1360호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하여 DNS 의미론을 따릅니다. `*://Mcp.Example.com/*`와 같은 패턴은 `https://mcp.example.com/api`와 일치하며, `https://mcp.example.com.`은 `https://mcp.example.com`과 동일하게 처리됩니다. 스킴과 경로는 대소문자를 구분합니다.

1361

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

1353 1363

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

mcp.md 2026-05-05 23:00 UTC to 2026-05-07 22:59 UTC

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

MCP로 할 수 있는 것

인기 있는 MCP 서버

MCP 서버 설치

옵션 1: 원격 HTTP 서버 추가

옵션 2: 원격 SSE 서버 추가

옵션 3: 로컬 stdio 서버 추가

서버 관리

동적 도구 업데이트

자동 재연결

채널을 사용한 메시지 푸시

플러그인 제공 MCP 서버

MCP 설치 범위

로컬 범위

프로젝트 범위

사용자 범위

범위 계층 및 우선순위

.mcp.json의 환경 변수 확장

실제 예

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

예: PostgreSQL 데이터베이스 쿼리

원격 MCP 서버로 인증

인증이 필요한 서버 추가

Claude Code 내에서 /mcp 명령 사용

고정 OAuth 콜백 포트 사용

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

서버로 OAuth 앱 등록

자격 증명으로 서버 추가

Claude Code에서 인증

OAuth 메타데이터 검색 재정의

OAuth 범위 제한

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

JSON 구성에서 MCP 서버 추가

JSON에서 MCP 서버 추가

서버가 추가되었는지 확인

Claude Desktop에서 MCP 서버 가져오기

Claude Desktop에서 서버 가져오기

가져올 서버 선택

서버가 가져와졌는지 확인

Claude.ai에서 MCP 서버 사용

Claude.ai에서 MCP 서버 구성

MCP 서버 인증

Claude Code에서 서버 보기 및 관리

Claude Code를 MCP 서버로 사용

MCP 출력 제한 및 경고

특정 도구의 제한 늘리기

MCP 리소스 요청에 응답

MCP 리소스 사용

MCP 리소스 참조

사용 가능한 리소스 나열

특정 리소스 참조

여러 리소스 참조

MCP Tool Search로 확장

작동 방식

MCP 서버 작성자용

Tool Search 구성

서버를 연기에서 제외

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

MCP 프롬프트 실행

사용 가능한 프롬프트 검색

인수 없이 프롬프트 실행

인수를 사용하여 프롬프트 실행

관리되는 MCP 구성

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

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

제한 옵션

구성 예

명령 기반 제한의 작동 방식

URL 기반 제한의 작동 방식

허용 목록 동작 (allowedMcpServers)

거부 목록 동작 (deniedMcpServers)

중요한 참고 사항

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

허용 목록 동작 (`allowedMcpServers`)

거부 목록 동작 (`deniedMcpServers`)