Claude Code MCP Server 가이드: SaaS 연동을 안전하게 시작하는 방법

MCP Server는 Claude Code를 단순한 로컬 코딩 도우미에서 GitHub, Notion, Google Drive, CRM, 내부 API까지 읽을 수 있는 업무 도구로 바꿉니다. 하지만 연결이 강력해질수록 위험도 커집니다. 잘못된 scope, 저장소에 들어간 token, 너무 넓은 OAuth 권한, Windows에서 실행되지 않는 npx, 10,000 token warning을 만드는 거대한 응답은 모두 실제 운영에서 자주 만나는 문제입니다.

이 글은 “일단 연결하기”가 아니라 “안전하게 도입하기”를 목표로 합니다. 작은 scope로 시작하고, .mcp.json에는 비밀값을 넣지 않으며, /mcp로 연결과 인증을 확인하고, 팀원이 읽을 수 있는 설정으로 남기는 절차를 정리합니다.

MCP가 Claude Code에서 바꾸는 것

MCP는 Model Context Protocol입니다. AI 클라이언트가 외부 도구와 데이터 소스에 연결하기 위한 표준이며, Claude Code는 MCP client로 동작합니다. MCP server는 tool을 제공하고 Claude Code는 세션 안에서 그 tool을 호출합니다.

MCP가 없을 때 Claude Code는 주로 저장소와 사용자가 붙여 넣은 문맥을 봅니다. MCP가 있으면 Issue, 문서, 고객 데이터, 제품 지표, 내부 SaaS까지 볼 수 있습니다. 그래서 첫 질문은 “어떤 server를 설치할까”가 아니라 “이 프로젝트가 어떤 데이터를 어떤 권한으로 봐도 되는가”입니다.

권한 경계는 Claude Code 권한 설정 가이드와 함께 보세요. 보안 관점은 Claude Code 보안 실천 가이드가 도움이 됩니다.

방식	용도	주의점
stdio	npx, Python, 사내 명령으로 로컬 server 실행	Windows에서는 cmd /c npx가 필요할 수 있음
http	원격 MCP, SaaS, OAuth	workspace와 권한 범위를 반드시 확인
sse	기존 SSE 기반 연동	신규 연동은 보통 HTTP 우선

scope를 먼저 정한다

claude mcp add에는 --scope local, --scope project, --scope user가 있습니다. 이 선택이 연결의 노출 범위를 결정합니다.

scope	의미	추천 용도
local	현재 프로젝트와 현재 머신에서만 사용	개인 검증, 고객별 연결, 비밀 정보가 있는 server
project	.mcp.json으로 저장되어 팀에 공유	이름과 명령을 팀에서 맞출 때
user	사용자의 모든 Claude Code 프로젝트에서 사용	정말 공통인 개인 도구

기본은 local입니다. 팀이 같은 server 정의를 써야 할 때만 project로 올립니다. project server는 승인 절차가 있으며, 이것은 귀찮은 단계가 아니라 외부 도구를 신뢰할지 묻는 안전 장치입니다.

claude mcp add --scope local --transport stdio repo-files -- npx -y @modelcontextprotocol/server-filesystem ./docs

claude mcp add --scope project --transport http team-docs https://mcp.example.com/mcp

claude mcp add --scope user --transport http personal-notes https://mcp.example.com/mcp

Windows에서는 cmd /c npx를 쓴다

Windows에서는 PowerShell에서 npx가 동작해도 Claude Code가 stdio MCP server를 시작할 때 실패할 수 있습니다. 이때는 cmd /c npx로 감싸는 패턴이 안정적입니다.

claude mcp add --scope local --transport stdio repo-files -- cmd /c npx -y @modelcontextprotocol/server-filesystem "C:\Users\masa\work\claudecode-lab\docs"

.mcp.json으로 작성할 때는 command와 args를 나눕니다.

{
  "mcpServers": {
    "repo-files": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\masa\\work\\claudecode-lab\\docs"
      ],
      "env": {}
    }
  }
}

처음부터 홈 디렉터리 전체를 넘기지 마세요. docs나 reports처럼 좁은 폴더에서 시작합니다. 쓰기 권한이 필요한 server라면 Claude Code Hooks 가이드를 함께 적용해 위험한 작업을 막습니다.

원격 MCP, OAuth, /mcp 확인

Notion, Google Drive, GitHub, CRM 같은 SaaS는 HTTP transport로 연결하는 경우가 많습니다.

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

추가 후 Claude Code 안에서 /mcp를 실행합니다. 여기서 연결 상태, OAuth 인증, 노출된 tool을 확인합니다.

/mcp

# 확인할 것
# - connected 상태인가
# - OAuth가 authenticated인가
# - 어떤 workspace를 승인했는가
# - tool 목록이 예상과 맞는가
# - read-only가 필요한데 write/admin tool이 있지는 않은가

내부 서비스에 bearer token이 필요하면 header로 넘길 수 있지만, token을 공유 파일에 저장하지 않습니다.

claude mcp add --scope local --transport http crm-readonly https://mcp.example.com/readonly \
  --header "Authorization: Bearer $CRM_READONLY_TOKEN"

팀용 .mcp.json은 연결 구조만 담습니다.

{
  "mcpServers": {
    "customer-docs": {
      "type": "http",
      "url": "https://mcp.example.com/customer-docs"
    },
    "github-readonly": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@example/github-readonly-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_READONLY_TOKEN}"
      }
    }
  }
}

사례1: GitHub와 Notion으로 Issue 조사

가장 빠른 효과는 Issue, PR, 사양 문서 사이의 이동을 줄이는 것입니다. GitHub MCP로 Issue를 읽고, Notion 또는 문서 MCP로 관련 요구사항을 찾은 뒤, Claude Code가 먼저 위험과 질문을 정리하게 합니다.

GitHub issue #248을 읽고 제품 문서에서 관련 요구사항을 찾아주세요.
아직 코드는 수정하지 마세요.
다음을 반환하세요:
1. 관련될 가능성이 높은 파일
2. 명확한 요구사항
3. 아직 모호한 점
4. 가장 작은 안전한 구현 계획

바로 구현시키지 않는 것이 핵심입니다. MCP로 문맥이 늘어나면 Claude Code가 빠르게 움직이지만, 그만큼 잘못된 확신도 빨라질 수 있습니다.

사례2: Google Drive 문서로 제안서 초안 만들기

컨설팅이나 교육 업무에서는 회의록, 기존 제안서, 가격표가 Drive에 흩어져 있습니다. 읽기 전용 MCP를 쓰면 Claude Code가 제안서 초안을 빠르게 만들 수 있습니다.

"2026-05 Customer A" 폴더를 검색하세요.
제안서 개요를 작성하세요:
1. 고객의 주요 문제 5개
2. 예상 구현 범위
3. 확인해야 할 미정 사항
4. 교육, 구현 지원, 운영 지원 3개 플랜

개인 이름, 이메일, 정확한 계약 금액은 가려주세요.

이 경우 안전 설계는 폴더 제한, read-only, 발송 전 인간 리뷰입니다. MCP는 정리를 빠르게 할 뿐 최종 판단을 대신하지 않습니다.

사례3: 읽기 전용 지표로 콘텐츠와 제품 의사결정

MCP는 제품 지표나 분석 API에도 연결할 수 있습니다. 하지만 데모가 멋지다고 운영 DB 쓰기 권한을 주면 안 됩니다. 분석에는 읽기 전용 endpoint가 충분합니다.

claude mcp add --scope local --transport http product-metrics https://mcp.example.com/readonly-metrics \
  --header "Authorization: Bearer $METRICS_READONLY_TOKEN"

최근 14일의 유입 경로, 글별 PV, 전환 클릭을 검토하세요.
주제별로 페이지를 묶고 다음에 쓸 글 주제 5개를 추천하세요.
각 추천에는 근거 수치와 데이터가 약한 부분을 포함하세요.

이 흐름은 수익화와 직접 연결됩니다. 감으로 글을 쓰는 대신 데이터를 보고 주제를 정하는 루프를 만들 수 있습니다.

10,000 token warning 처리

MCP tool 응답이 너무 크면 Claude Code에 10,000 token warning이 나옵니다. 문서 검색이 본문 전체를 반환하거나, Issue 목록이 너무 길거나, DB query가 제한 없이 row를 반환할 때 자주 생깁니다.

먼저 출력 자체를 줄입니다.

최대 10개 결과만 반환하세요.
각 결과는 제목, URL, 수정일, 관련 이유만 포함하세요.
본문은 반환하지 마세요. 필요하면 한 건씩 요청하겠습니다.

일회성 분석에서는 MAX_MCP_OUTPUT_TOKENS를 늘릴 수 있습니다.

MAX_MCP_OUTPUT_TOKENS=50000 claude

$env:MAX_MCP_OUTPUT_TOKENS = "50000"
claude

매일 이 설정이 필요하다면 server 설계를 바꿔야 합니다. pagination, filter, summary endpoint를 추가하세요.

자주 나는 실패

첫째, .mcp.json에 비밀값을 넣는 것입니다. project scope 설정은 공유 대상입니다. token은 환경 변수나 OAuth로 분리합니다.

둘째, 편해서 --scope user를 쓰는 것입니다. 고객별 연결이 다른 프로젝트에 보일 수 있습니다.

셋째, MCP로 읽은 외부 문서를 명령으로 믿는 것입니다. 외부 텍스트는 데이터이지 실행 지시가 아닙니다.

넷째, OAuth 후 /mcp를 보지 않는 것입니다. 로그인 성공과 올바른 workspace 승인은 다릅니다.

다섯째, 큰 출력에 의존하는 것입니다. 안정적인 업무 흐름은 전체 데이터를 던지는 방식이 아니라 요약과 필터를 사용합니다.

점검 명령

claude mcp list
claude mcp get repo-files

Claude Code 안에서는:

/mcp

project server approval을 다시 선택하려면:

claude mcp reset-project-choices

작은 smoke test:

repo-files MCP 연결만 확인하세요.
허용된 디렉터리 바로 아래 파일명을 최대 10개만 보여주세요.
파일 내용은 읽지 말고 아무것도 수정하지 마세요.

수익화 관점

MCP는 팀이 실제로 쓰는 SaaS와 Claude Code를 연결하므로 수익화에 가깝습니다. 하지만 “MCP server를 설치합니다”보다 “GitHub, Notion, Google Drive, 내부 SaaS를 안전하게 Claude Code에 연결해 팀 업무를 빠르게 합니다”가 더 강한 제안입니다.

• 개인용: .mcp.json 템플릿과 안전 체크리스트
• 팀용: GitHub, Notion, Drive, 권한 경계 리뷰
• 법인용: scope, OAuth, hooks, 모니터링, 교육까지 포함한 도입 지원

처음에는 테스트 폴더에서 filesystem 예제를 실행하세요. 팀이라면 하나의 read-only SaaS와 하나의 project-scoped .mcp.json으로 시작하고, Claude Code Harness Engineering의 안전한 작업 발판과 결합하세요.

이 글은 Claude Code 공식 MCP 문서의 claude mcp add, scope, .mcp.json, /mcp, OAuth, project server approval, MAX_MCP_OUTPUT_TOKENS에 맞춰 정리했습니다. 원칙은 작게 시작하고, 읽기 전용으로 검증하고, 비밀을 공유하지 않으며, 매번 연결 상태를 확인하는 것입니다.