외부 코드는 작성할 수 있지만 사내 컨텍스트는 전혀 모른다──Claude Code의 최대 약점을 3개의 MCP 서버로 메운 1개월간의 기록.

Claude Code는 우수합니다. 코드 생성, 리팩터링(Refactoring), 테스트 작성 모두 높은 정밀도로 응답해 줍니다.

하지만, 사내 사정에 대해서는 아무것도 모릅니다.

• "우리 사용자 테이블의 컬럼 정의는 이렇고..."
• "이 설계 판단은 ADR #023에 적혀 있는데..."
• "지난달 Slack에서 논의한 결과, 이 방침이 되었는데..."

매번 이를 설명하는 프롬프트(Prompt)를 작성해야 했습니다. 팀원 5명이 각자 고유한 '전제 설명 템플릿'을 가지고 있는 상태. 이는 분명히 비정상적입니다.

그래서 MCP (Model Context Protocol) 서버를 3개 직접 제작하여, Claude Code에서 사내의 Notion, Slack, PostgreSQL에 직접 액세스할 수 있도록 했습니다. 결과적으로 전제 설명 프롬프트의 글자 수가 평균 72% 감소했습니다. Claude Code가 '사내 사정을 아는 에이전트'로 변했습니다.

먼저 완성된 형태의 구성을 보여드립니다.

포인트는 3가지입니다.

• 각 MCP 서버는 독립된 프로세스로 동작하며, Claude Code의 설정 파일로 묶는다 -
• 보안 레이어(Security Layer)를 MCP 서버 내부에 구현한다 (외부 API와 Claude Code 사이에 필터를 끼워 넣는다) -
• 각 서버는 stdio 통신으로 접속하며, 로컬에서 완결된다

1. Notion MCP 서버: 설계 문서 참조

설계 문서(ADR, API 사양, ER 다이어그램 설명문)를 Claude Code에서 참조할 수 있게 합니다.

Notion MCP 서버에서는 다음 3가지 도구(Tool)를 공개했습니다.

// tools 정의 (발췌)
const tools = [
{
...

{
"mcpServers": {
"notion-docs": {
...

이것만으로 Claude Code에 /search_design_docs라고 입력할 필요조차 없이, "우리 사용자 인증의 설계 방침을 알려줘"라고 묻기만 해도 ADR을 검색하여 답변해 주는 상태가 되었습니다.

2. Slack MCP 서버: 기술 논의 히스토리 참조

과거의 기술 논의 스레드를 검색하여, "왜 이 구현이 되었는가"라는 경위를 Claude Code에 주입합니다.

const tools = [
{
name: "search_tech_threads",
...

검색 대상 채널을 화이트리스트(Whitelist) 방식으로 운영하는 것이 중요합니다. #general이나 #random, HR 관련 채널은 절대로 포함하지 않습니다. 이에 대해서는 후술할 "예상치 못했던 점 ②"에서 자세히 다루겠습니다.

3. PostgreSQL MCP 서버: DB 스키마 및 샘플 데이터 참조

테이블 정의(Schema)와 샘플 데이터를 Claude Code에서 참조하여, SQL 및 마이그레이션(Migration) 생성 정밀도를 높입니다.

구체적으로는 다음과 같은 규칙을 세웠습니다.

// 샘플 데이터 취득 시의 마스킹 처리 (발췌)
const MASKED_COLUMNS = ["email", "phone", "name", "first_name", "last_name"];
function maskRow(row: Record<string, unknown>): Record<string, unknown> {
...

임의의 SQL을 실행하게 하지 않는 것이 가장 중요한 포인트입니다. MCP 서버가 제공하는 것은 get_table_schema, get_sample_data, list_tables 이 3가지 툴뿐입니다. Claude Code가 "이 SQL을 실행해줘"라고 말하더라도, MCP 서버 측에서 차단합니다.

Notion 페이지에는 중첩된 블록이 있어, 페이지 하나를 가져오는 것만으로도 수천~수만 토큰이 되는 경우가 있었습니다. 설계 문서는 그림이나 테이블이 많아 특히 비대해지기 쉽습니다.

이는 Claude Code의 컨텍스트 윈도우 (Context Window)를 압박하여, 정작 중요한 코드 생성에 사용할 수 있는 토큰이 줄어드는 본말전도 상황을 초래했습니다.

구현으로는 다음과 같은 접근 방식을 취했습니다.

• 섹션 헤딩 추출: H1~H3 헤딩만 뽑아낸 "목차"를 먼저 반환
• 섹션 단위 취득: Claude Code가 필요한 섹션만 추가로 가져올 수 있는 툴을 마련
• 캐시 (Cache): 동일한 페이지에 대한 요청은 1시간 동안 캐시

// 페이지 내용을 구조화하여 반환
function structurePage(blocks: NotionBlock[]): StructuredPage {
const sections = extractSections(blocks); // H1-H3로 분할
...

이를 통해 1회 요청 시 소비되는 토큰을 평균 85% 절감할 수 있었습니다.

테스트 중, Claude Code에게 "인증 관련 과거 논의를 찾아줘"라고 요청했더니, Slack 검색 결과에 운영 환경의 API 키가 평문으로 붙어 있는 스레드가 포함되어 있었습니다.

MCP 서버가 응답을 그대로 반환하고 있었기 때문에, Claude Code의 컨텍스트에 API 키가 들어가 버린 것입니다.

최종적으로 다음과 같은 3개 계층에서 필터링하는 설계로 결정했습니다.

// 제2계층: 기밀 정보 탐지 및 치환
const SECRET_PATTERNS = [
/(?:api[_-]?key|secret|token|password)\s*[:=]\s*\S+/gi,
...

이 필터링 설계는 Notion MCP 서버에도 수평 전개했습니다. Notion에도 가끔 기밀 정보가 적혀 있는 경우가 있기 때문입니다.

도입 3주 후, 팀원 5명의 이용 데이터를 집계했습니다.

특히 "스키마 알려줘" 계열의 질문이 거의 사라진 점이 큽니다. Claude Code가 스스로 DB MCP 서버에 문의하여 테이블 정의를 가져온 뒤 코드를 작성해 주기 때문입니다.

체감상으로도 "Claude Code가 같은 팀의 멤버가 되었다"는 느낌입니다. "우리 orders 테이블에 status 컬럼을 추가하는 마이그레이션(Migration)을 작성해줘"라고 말하면, 기존 스키마를 확인하고, ADR 명명 규칙을 참조하여 적절한 마이그레이션 파일을 생성해 줍니다.

MCP 서버의 본질은 API 래퍼 (Wrapper)가 아닙니다.

조직의 암묵지를 AI가 참조 가능한 형태로 구조화하는 인프라입니다.

지금까지 Claude Code는 "우수하지만 신입 사원"이었습니다. 무엇을 물어도 그럴듯한 답변을 주지만, 사내 맥락을 모릅니다. 매번 온보딩이 필요했습니다.

MCP 서버 3개를 구축함으로써, Claude Code는 "사내 사정을 잘 아는 시니어 엔지니어"에 가까워졌습니다. 완벽하지는 않지만, 적어도 "우리 DB의 컬럼명"이나 "왜 이런 설계를 했는지"를 스스로 찾아봅니다.

• MCP 서버는 "AI에게 조직의 기억을 부여하는" 인프라이며, Notion·Slack·DB 3개를 연결하는 것만으로 전제 설명 프롬프트가 72% 감소했다.
• 보안 설계는 필수이다. 특히 Slack 연동에서는 기밀 정보 필터링, DB 연동에서는 읽기 전용 (READ ONLY) 권한 + 데이터 마스킹 (Data Masking)을 다층적으로 구현해야 한다.
• 토큰 압박에 대한 대책으로, Notion과 같은 리치 콘텐츠는 "목차 $\rightarrow$ 섹션 단위 취득"의 2단계 아키텍처가 유효하다.