Claude Code가 사내 API 문서와 Notion의 사양서를 "직접 읽으러 갈 수 있는" 상태를 만들었더니, 프롬프트에 일일이 붙여넣어야 했던 복사 붙여넣기 지옥에서 해방되었습니다.
이 기사에서는 자사 REST API의 OpenAPI spec을 읽어들이는 MCP 서버와, Notion 데이터베이스를 MCP를 통해 Claude Code에 연결하는 서버 두 가지를 실제로 구축하는 핸즈온을 제공합니다.
읽고 나면 다음과 같은 것들을 할 수 있게 됩니다.
- 자사 API의 사양을 Claude Code가 자율적으로 참조할 수 있는 환경 구축
- Notion의 지식 베이스(Knowledge Base)를 검색·취득하는 MCP 서버 구축
- 복수의 MCP 서버 설정 관리와 보안 설계
| 항목 | 버전 / 요구사항 |
|---|
| Claude Code | 최신 버전 (CLI) |
| ... | |
사전에 다음을 준비해 주세요.
- Claude Code 설치 및 인증된 환경
- Notion Integration (API 토큰) 생성
- 자사 API의 OpenAPI spec (JSON 또는 YAML)
먼저, Claude Code에서 MCP 서버군으로의 접속 모델을 정리합니다.
MCP (Model Context Protocol)는 LLM이 외부 데이터 소스나 도구에 **표준화된 프로토콜 (Standardized Protocol)**로 액세스하기 위한 메커니즘입니다. Claude Code는 **MCP 클라이언트 (MCP Client)**로서 동작하며, 각 MCP 서버가 제공하는 "도구 (Tool)"나 "리소스 (Resource)"를 호출합니다.
포인트는 세 가지입니다.
Claude Code는 MCP 클라이언트로서 표준 프로토콜로 통신한다 — 서버의 구현 언어를 불문함 -
각 MCP 서버는 독립된 프로세스로 동작한다 — 장애의 영향 범위가 한정됨 -
인증 정보는 MCP 서버 측에서 관리한다 — Claude Code 본체에 토큰을 전달하지 않음
mkdir openapi-mcp-server && cd openapi-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod yaml node-fetch
...
src/index.ts를 작성합니다.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
...
# 빌드 & 기동 테스트
npx tsx src/index.ts
MCP Inspector로 동작 확인을 할 때는 다음을 사용합니다.
npx @modelcontextprotocol/inspector npx tsx src/index.ts
- Notion Integrations에서 새로운 Integration을 생성
- 대상 데이터베이스에 대해 Integration을 커넥트 (Connect) 한다 (페이지 우측 상단의 "..." → "Connect") - Internal Integration Secret을 기록해 둔다
mkdir notion-mcp-server && cd notion-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk @notionhq/client zod
...
src/index.ts를 작성합니다.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { Client } from "@notionhq/client";
...
Claude Code에서는 프로젝트 루트의 .mcp.json 또는 **~/.claude.json**으로 MCP 서버를 관리합니다.
~/.claude.json은 팀에서 공유하는 프로젝트 단위의 설정입니다.
{
"mcpServers": {
"openapi": {
...
포인트: env
{{NOTION_API_TOKEN}}
라고 작성하면, Claude Code가 첫 연결 시 사용자에게 값 입력을 요청합니다. 토큰을 설정 파일에 하드코드(Hardcode)하지 않아도 되는 메커니즘입니다.
개인의 모든 프로젝트에서 공통으로 사용하고 싶은 서버는 여기에 설정합니다.
{
"mcpServers": {
"slack": {
...
CLI를 통한 추가도 가능합니다.
# 프로젝트 스코프(Project Scope)에 추가
claude mcp add openapi -- npx tsx ./openapi-mcp-server/src/index.ts
# 유저 스코프(User Scope)에 추가
...
| 방법 | 안전성 | 간편함 | 권장도 |
|---|
.mcp.json에 {{VAR}} 형식으로 기술 | ◎ | ○ | ★★★ |
| 환경 변수(Environment Variable)로 직접 전달 | ○ | ◎ | ★★☆ |
.env 파일 + dotenv | △ | ◎ | ★☆☆ |
| 하드코드 (Hardcode) | × | ◎ | ☆☆☆ |
가장 권장되는 방식은 {{VAR}} 형식입니다.
.mcp.json은 Git에 커밋하여 팀과 공유하면서도, 실제 토큰 값은 각 개발자의 로컬(Local)에만 저장됩니다. Notion MCP 서버에서는 Integration 측에서 액세스를 허용할 페이지 및 데이터베이스를 한정합니다.
// 서버 측에서도 추가 유효성 검사(Validation)를 수행
const ALLOWED_DATABASE_IDS = (process.env.ALLOWED_DB_IDS || "").split(",");
server.tool(
...
.claudeignore는 Claude Code가 프로젝트 내의 파일을 읽을 때의 액세스 제어(Access Control)입니다. MCP 서버의 토큰 파일이나 기밀 설정을 제외합시다.
# .claudeignore
.env
.env.*
...
저의 팀(4명)에서 2주간 운용한 결과를 공유합니다.
- 대상 태스크: 자사 API를 사용한 신규 기능 구현 및 버그 수정
- 비교 기간: MCP 도입 전 2주 vs 도입 후 2주
- 측정 방법: Claude Code의 조작 로그 + 자기 신고 작업 기록
| 지표 | 도입 전 | 도입 후 | 개선율 |
|---|
| 1개 태스크당 컨텍스트(Context) 붙여넣기 횟수 | 평균 4.2회 | 평균 0.8회 | -81% |
| ... | | | |
가장 큰 변화는 **"Claude Code가 스스로 API 사양을 확인해 준다"**는 점에 따른 인지 부하(Cognitive Load)의 감소입니다. "이 엔드포인트의 요청 바디(Request Body) 형식은?"과 같은 확인을 AI가 자율적으로 수행하기 때문에, 개발자는 비즈니스 로직에 집중할 수 있게 되었습니다.
MCP 서버는 "Claude Code의 눈과 손"을 확장하는 메커니즘입니다. OpenAPI spec이나 Notion의 지식 베이스(Knowledge Base)를 연결함으로써, 복사 및 붙여넣기를 통한 컨텍스트 주입으로부터 해방됩니다.
구축은 생각보다 심플합니다. @modelcontextprotocol/sdk를 사용하면, 파일 1개당 100~150줄 정도로 3개의 도구(Tool)를 가진 MCP 서버를 만들 수 있습니다.
보안은 "토큰을 설정 파일에 하드코드하지 않는다", "MCP 서버 측에서 액세스 범위를 좁힌다", ".claudeignore로 기밀 파일을 제외한다"의 3가지 포인트를 지킨다면 실운영에 견딜 수 있습니다.
