MCP 커스텀 서버: DB·로컬 API를 Claude 에이전트에 연결하기

파워 유저에게 MCP가 중요한 이유

MCP 이전에는 IDE마다 제각각 플러그인 형식을 사용했습니다. Anthropic의 Model Context Protocol은 AI 클라이언트가 기능을 발견하는 방식을 표준화합니다: 도구 목록 조회 → JSON 인자로 도구 호출 → 구조화된 결과 반환. 즉, 하나의 Postgres 읽기 전용 서버가 Claude Desktop, Cursor, 기타 MCP 호스트에 통합을 다시 작성하지 않고 서비스할 수 있습니다.

하드코어 개발자가 MCP에 주목하는 이유:

• 데이터베이스를 매 채팅마다 스키마 덤프를 붙여 넣지 않고도 쿼리 가능한 컨텍스트로 전환
• 내부 API(빌링, 기능 플래그, 배포 상태)를 복사·붙여넣기 대신 타입이 있는 도구로 노출
• IDE + 에이전트 스택이 원격 Mac에서 Claude Code 대안이나 OpenClaw를 함께 실행할 때 동일한 툴체인 공유

공식 참고: Model Context Protocol 사양 및 Anthropic MCP 문서.

60초 MCP 아키텍처

┌─────────────┐     JSON-RPC      ┌──────────────────┐
│  MCP Host   │ ◄──────────────► │  MCP Server       │
│ (Claude /   │   tools/resources │ (your custom code)│
│  Cursor)    │                   │  → DB / API / CLI │
└─────────────┘                   └──────────────────┘

깊이 규칙: 신뢰 경계(trust boundary)마다 서버 하나. 프로덕션 쓰기 권한과 실험적 셸 도구를 같은 서버 바이너리에 넣지 마세요 — 프로세스를 분리하면 설정 블록 하나만 철회하고 다른 쪽은 그대로 둘 수 있습니다.

전송 방식 결정 매트릭스

패턴 1 — 데이터베이스 MCP 서버

목표: 모델이 PostgreSQL, MySQL, SQLite에 대해 읽기 전용 SQL(또는 사전 정의 쿼리)을 실행할 수 있게 합니다.

설계 제약:

• 가능하면 임의 SQL 대신 명명된 도구(query_sales_summary, list_tables) 노출
• 행 상한(예: 최대 200행)과 문 타임아웃(예: 5초) 강제
• 연결 문자열을 모델에 전달하지 말고 서버 환경의 DATABASE_URL에서 로드

읽기 전용 DB 역할 사용: GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_reader;

패턴 2 — 로컬 REST API 게이트웨이

목표: 기존 HTTP 엔드포인트를 MCP 도구로 감싸 Claude가 채팅 창에 장기 API 키를 보관하지 않게 합니다.

게이트웨이 패턴:

Claude → MCP tool "deploy_status" → your server → GET https://internal/api/v1/deployments

구현 팁:

• 각 도구를 HTTP 메서드 + 경로 템플릿 하나에 매핑
• fetch 호출 전 스키마(Zod, Pydantic)로 입력 검증
• 응답이 크면 잘린 JSON(처음 8 KB)과 truncated: true 플래그 반환
• 상관 ID는 서버 측 로그; 도구 결과에 시크릿을 에코하지 않음

OpenClaw 워커가 ad-hoc curl 대신 MCP로 같은 내부 API를 호출할 때 멀티 에이전트 오케스트레이션과 잘 맞습니다.

패턴 3 — IDE 및 레포 브리지

Cursor와 Claude Code는 이미 MCP 클라이언트를 내장합니다. 커스텀 서버가 노출할 수 있는 것:

• 레포 도구: git_diff_summary, run_linter(샌드박스)
• 문서 리소스: AGENTS.md, OpenAPI 스펙에 대한 file:// 또는 resources/read
• ECC / 플러그인 훅: ECC 설치 후 팀 ecc 스크립트를 감싸는 MCP 도구 추가

팀 전체가 하나의 원격 개발 박스를 공유하지 않는 한 IDE 브리지는 stdio-로컬을 유지하세요.

8단계 런북

1단계 — 공식 SDK 설치

Node(대부분 호스트에 권장):

mkdir mcp-company-gateway && cd mcp-company-gateway
npm init -y
npm install @modelcontextprotocol/sdk zod pg

Python 대안: pip install mcp(MCP Python SDK 참조).

2단계 — 최소 서버 스캐폴딩

src/index.ts 생성:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "company-gateway", version: "1.0.0" });

server.tool("ping", {}, async () => ({
  content: [{ type: "text", text: "pong" }],
}));

const transport = new StdioServerTransport();
await server.connect(transport);

한 번 실행: npx tsx src/index.ts — stdio 대기로 블록(출력 없음이 정상).

3단계 — 읽기 전용 Postgres 도구 추가

export DATABASE_URL="postgresql://mcp_reader:****@127.0.0.1:5432/app"

SELECT로 시작하는 SQL만 허용하도록 Zod 검증(; 및 DDL 키워드 서버 측 거부)으로 postgres_query_readonly 등록.

4단계 — Claude Desktop에 등록

macOS에서 ~/Library/Application Support/Claude/claude_desktop_config.json 편집:

{
  "mcpServers": {
    "company-gateway": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/mcp-company-gateway/src/index.ts"],
      "env": { "DATABASE_URL": "postgresql://mcp_reader@127.0.0.1:5432/app" }
    }
  }
}

Claude Desktop 재시작. 새 채팅에서 망치/도구 아이콘에 ping과 postgres_query_readonly가 보이는지 확인.

5단계 — Cursor에 등록

프로젝트 또는 전역 .cursor/mcp.json:

{
  "mcpServers": {
    "company-gateway": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/mcp-company-gateway/src/index.ts"]
    }
  }
}

Cursor 창 리로드. 에이전트 패널에서 동일한 ping 도구 테스트.

6단계 — 원격 호스트용 SSE 노출(선택)

MCP 서버가 원격 Mac(팀 배스천 또는 렌탈 M4)에서 실행될 때:

# Example: SDK HTTP/SSE transport on port 8787 — bind localhost only unless behind VPN
node dist/sse-server.js --port 8787 --host 127.0.0.1

SSH 터널로 호스트 설정을 url: "http://127.0.0.1:8787/sse"에 연결:

ssh -L 8787:127.0.0.1:8787 user@remote-mac

SSE 원격 운영 시 서울 리전 상시 가동 Mac mini 노드도 선택지입니다. 인증 없는 MCP SSE 포트를 공용 인터넷에 노출하지 마세요.

7단계 — 시크릿과 샌드박싱

8단계 — MCP Inspector로 검증

npx @modelcontextprotocol/inspector npx tsx src/index.ts

호스트 UI를 신뢰하기 전에 tools/list와 tools/call을 수동 호출. 모든 도구 호출을 타임스탬프 + OS 사용자(채팅 내용 아님)로 감사 로그.

보안 및 샌드박스 체크리스트

• 분석 도구에는 읽기 전용 DB 역할; 쓰기 도구는 개발 머신 전용 두 번째 서버
• 모든 도구에 입력 검증; 32 KB 초과 중첩 객체 거부
• 내부 API 래핑 시 서버 프로세스 네트워크 egress 허용 목록(iptables 또는 macOS 방화벽)
• SaaS OAuth — 서버 내부에서 토큰 갱신; 모델에는 불투명 tool_ok만 노출

전용 Mac에서 MCP를 실행할 때

노트북 절전은 stdio 서버를 종료합니다. 공유 MCP 카탈로그(8명 엔지니어가 같은 Postgres 도구 사용)를 원하는 팀은 서버를 상시 가동 Apple Silicon Mac — 책상 옆 또는 소형 원격 노드 — 에 두고 SSH 터널 또는 VPN으로 접근합니다.

이는 MCP 요구사항이 아니라 인프라 선택입니다. 16 GB M4는 Node 툴링과 함께 가벼운 MCP 서버 프로세스 3~5개(각 ~80–150 MB)를 여유 있게 실행합니다. 같은 박스에서 Docker DB도 돌리면 RAM을 추가하세요.

문제 해결

오류: spawn 직후 Connection closed

패턴: Claude Desktop 로그에 서버 종료 코드 1. 수정: 터미널에서 동일한 command + args 실행; tsx 누락, 잘못된 절대 경로, 시작 시 예외 수정. MCP 호스트는 UI에 stderr를 표시하지 않습니다.

오류: Tool not found / 빈 도구 목록

패턴: 설정 JSON 서버 이름 오타 또는 호스트 미리로드. 수정: jq . claude_desktop_config.json으로 JSON 검증; 창만 닫지 말고 호스트 앱 완전 종료 후 재실행.

오류: SSE 404 또는 CORS 실패

패턴: 원격 URL 경로 오류(/sse vs /mcp). 수정: SDK HTTP 전송 문서의 경로와 일치; ssh -L 터널 후 설정에는 127.0.0.1 사용.

권장 경로

만약 X → Y: 데이터가 다른 머신에 있으면 MCP 서버를 데이터 옆에 두고 호스트로 터널 — Claude에 공용 인터넷 DB 포트를 주지 마세요.

FAQ

MCP와 ChatGPT 플러그인의 차이는 무엇인가요?

MCP는 여러 언어 SDK를 갖춘 개방형·호스트 독립적 JSON-RPC 프로토콜입니다. 플러그인은 플랫폼 전용이었습니다. MCP 서버는 사용자가 제어하는 로컬 또는 원격 프로세스로 실행되며, 호스트는 spawn하거나 연결만 합니다.

PostgreSQL과 같은 방식으로 MySQL이나 SQLite를 연결할 수 있나요?

예. 서버 구현(드라이버 + SQL 방언)만 바뀌고 MCP 표면(list_tools, call_tool)은 동일합니다. 읽기 전용 연결과 방언별 가드(SELECT 전용)를 사용하세요.

Claude Code는 MCP 커스텀 서버를 지원하나요?

2026년 기준 Claude Code와 Cursor 모두 Claude Desktop과 유사한 MCP 클라이언트 설정을 지원합니다. 제품별 mcpServers 경로는 다를 수 있으나 — 현재 Anthropic·Cursor 문서 확인 — 작성한 서버 코드는 호스트 간 재사용 가능합니다.

하나의 서버에 몇 개의 도구를 노출해야 하나요?

서버당 약 20개 이하가 모델 라우팅에 안정적입니다. 카탈로그가 커지면 billing-gateway, data-gateway, ops-gateway처럼 분리. 각각 호스트 설정에서 별도 블록으로 표시됩니다.

쓰기 도구(DELETE, deploy)를 노출해도 안전한가요?

명시적 사람 확인 흐름이 있는 비프로덕션 서버에서만 허용하세요. 공유 설정에는 읽기 도구를 우선하고, 쓰기는 시니어 개발자만 개인 설정에서 활성화하는 두 번째 MCP 서버로 분리하세요.