MCP 서버 구축 2026, 사내 도구 연결 전 설치·권한·운영 기준
MCP 서버 구축을 검색한 사람은 보통 샘플 서버 하나를 띄우는 방법보다 사내 도구를 어디까지 연결해도 되는지 먼저 궁금해한다.
AI가 이슈 트래커, 문서 저장소, 데이터베이스, 모니터링 화면을 직접 읽기 시작하면 작은 테스트 서버도 운영 시스템의 입구가 된다.
그래서 2026년 MCP 서버 구축은 설치 명령보다 도구 범위, 승인 흐름, 감사 로그, 비용 한도를 같은 문서에 묶어야 한다.
이 글은 MCP 공식 문서, 전송 규격, 보안 권고, Claude Code 연결 문서를 바탕으로 파일럿 서버를 안전하게 올리는 순서를 정리한다.
- MCP는 AI 애플리케이션과 외부 시스템을 연결하는 공개 표준이지만 서버가 노출하는 도구는 실제 업무 권한으로 이어진다.
- 첫 파일럿은 stdio 기반 로컬 서버로 시작하고, 원격 HTTP 서버는 인증과 Origin 검증을 설계한 뒤 열어야 한다.
- 도구는 읽기 전용, 쓰기 작업, 외부 전송, 비용 발생 작업으로 나누고 기본 승인 정책을 다르게 둔다.
- MCP 서버 구축 성공 기준은 데모 동작이 아니라 감사 로그, 장애 롤백, 비밀값 분리, 예산 한도가 확인되는 것이다.
이 글이 필요한 사람
- Claude Code나 사내 AI 에이전트에서 Jira, GitHub, Notion, DB, 모니터링 도구를 연결하려는 개발팀
- MCP 서버 구축을 파일럿으로 시작하지만 보안팀 승인 문서까지 같이 준비해야 하는 플랫폼 팀
- stdio 서버와 원격 HTTP 서버 중 어떤 방식으로 운영할지 결정해야 하는 DevOps 담당자
- AI 도구 호출 로그, 사용자 승인, 토큰 보관, 비용 한도를 내부 통제 항목으로 올려야 하는 보안 담당자
- 기존 API를 MCP로 감싸려는데 모델이 어떤 입력을 보낼지 걱정하는 백엔드 개발자
MCP 서버 구축 전에 정해야 할 경계
MCP 공식 소개는 MCP를 AI 애플리케이션과 외부 시스템을 연결하는 표준이라고 설명한다.
서버 개념 문서는 MCP 서버가 tools, resources, prompts 세 가지 기능을 제공한다고 구분한다.
실무에서는 이 세 구분이 곧 권한 경계가 되므로 한 서버에 모든 기능을 몰아넣으면 검토가 어려워진다.
| 구분 | 실무 의미 | 기본 위험 | 파일럿 기준 | 승인 담당 |
|---|---|---|---|---|
| Tools | 모델이 호출하는 함수이며 파일 수정, API 호출, 티켓 생성으로 이어질 수 있다. | 권한 남용과 비용 발생 | 읽기 전용부터 시작한다. | 서비스 오너와 보안팀 |
| Resources | 문서, 스키마, 로그처럼 클라이언트가 읽는 컨텍스트다. | 민감정보 노출 | 공개 가능한 범위를 URI 단위로 나눈다. | 데이터 오너 |
| Prompts | 사용자가 고르는 작업 템플릿이다. | 업무 지시 오해 | 입력값과 결과 검토자를 명시한다. | 업무 담당자 |
| Transports | stdio 또는 HTTP로 메시지를 주고받는 경로다. | 노출면 확대 | 로컬 stdio 후 원격 HTTP를 검토한다. | 플랫폼 팀 |
MCP 서버 구축의 첫 결정은 어떤 기능을 만들지가 아니라 어떤 기능을 아직 만들지 않을지 정하는 것이다.
첫 서버는 로컬 stdio로 작게 만든다
MCP 공식 서버 가이드는 Python 서버 예제에서 FastMCP를 사용해 도구를 정의하는 흐름을 보여준다.
같은 문서는 stdio 기반 서버에서 stdout에 일반 로그를 쓰면 JSON-RPC 메시지가 깨질 수 있다고 경고한다.
따라서 사내 파일럿은 로그 출력 위치와 입력 검증을 먼저 고정한 뒤 실제 API를 연결하는 편이 안전하다.
- Python 3.10 이상과 MCP Python SDK를 사용할 수 있는 개발 환경을 준비한다.
- 빈 프로젝트를 만들고 SDK와 HTTP 클라이언트 같은 최소 의존성만 추가한다.
- 서버 파일에 FastMCP 인스턴스를 만들고 읽기 전용 도구 하나만 등록한다.
- 도구 입력 길이, 허용 컬렉션, 결과 개수 같은 제한을 서버 코드에서 검증한다.
- stdio 서버는 stdout을 프로토콜 메시지 전용으로 두고 일반 로그는 stderr나 파일로 보낸다.
- 클라이언트 설정 파일에 서버 명령, 인자, 환경변수를 등록하고 비밀값은 직접 쓰지 않는다.
- 실제 업무 데이터 연결 전에는 더미 응답과 감사 로그 필드만 먼저 검증한다.
이 흐름이면 MCP 서버 구축 파일럿에서 데모 속도와 통제 기준을 동시에 잡을 수 있다.
Python MCP 서버 스켈레톤
아래 예시는 실제 내부 검색을 호출하지 않고 입력 검증과 권한 범위를 먼저 보여주는 서버 스켈레톤이다.
# server.py
# 목적: 사내 문서 검색 도구를 MCP 서버로 노출하기 전 구조를 검증한다.
# 실제 데이터베이스, 토큰, 내부 URL은 환경변수와 비밀 저장소로 분리한다.
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("internal-knowledge")
ALLOWED_COLLECTIONS = {"runbook", "policy", "incident"}
@mcp.tool()
def search_internal_docs(collection: str, query: str, limit: int = 5) -> dict:
# 입력 검증은 모델을 믿지 말고 서버에서 한 번 더 수행한다.
if collection not in ALLOWED_COLLECTIONS:
return {"error": "collection_not_allowed"}
if not query or len(query) > 120:
return {"error": "query_length_invalid"}
if limit < 1 or limit > 10:
return {"error": "limit_out_of_range"}
# 실제 검색 호출 전 감사 로그에 사용자, 도구, 승인 ID를 남긴다.
return {
"collection": collection,
"query": query,
"items": [],
"note": "connect real search backend after security review",
}
if __name__ == "__main__":
# stdio 서버에서는 stdout에 일반 로그를 쓰면 JSON-RPC 메시지가 깨진다.
mcp.run(transport="stdio")이 예시는 복붙 배포용 완성 코드가 아니라 보안 리뷰에서 논의할 최소 구조를 남기는 목적이다.
실제 연결 단계에서는 도구별 서비스 계정, 네트워크 경로, 결과 마스킹, 사용자 승인 ID를 붙여야 한다.
클라이언트 연결과 첫 실행 확인
Claude Code 문서는 MCP 서버를 HTTP, SSE, stdio 방식으로 추가할 수 있다고 안내한다.
문서 기준으로 원격 연결은 HTTP가 기본 선택지이고 SSE는 가능한 경우 HTTP로 대체하는 흐름이 안전하다.
로컬 stdio 서버는 프로젝트 내부 스크립트와 직접 연결하기 좋지만 실행 권한과 로그 위치를 더 엄격히 봐야 한다.
{
"mcpServers": {
"internal-knowledge": {
"command": "uv",
"args": ["run", "python", "server.py"],
"env": {
"MCP_AUDIT_LOG": "stderr",
"MCP_ENV": "pilot"
}
}
}
}- 클라이언트에서 서버 목록이 보이는지 먼저 확인한다.
- 도구 목록에 읽기 전용 도구 하나만 노출되는지 확인한다.
- 허용되지 않은 collection 입력이 거부되는지 확인한다.
- 긴 query와 과도한 limit 값이 서버에서 차단되는지 확인한다.
- 도구 호출 결과에 원문 토큰, 이메일, 세션 값이 섞이지 않는지 확인한다.
- 승인 대화상자나 감사 로그에서 사용자, 도구명, 입력 해시, 결과 상태가 남는지 확인한다.
MCP 서버 구축 테스트는 첫 응답 성공보다 실패 입력이 예상대로 막히는지를 더 중요하게 봐야 한다.
stdio와 Streamable HTTP 선택 기준
MCP 전송 규격은 표준 전송으로 stdio와 Streamable HTTP를 정의한다.
stdio는 클라이언트가 서버 프로세스를 띄워 stdin과 stdout으로 JSON-RPC 메시지를 주고받는 방식이다.
Streamable HTTP는 서버가 독립 프로세스로 동작하며 POST와 GET 요청을 처리하는 방식이다.
| 선택지 | 맞는 상황 | 주의할 점 | 운영 기준 |
|---|---|---|---|
| stdio | 개발자 로컬 도구, 프로젝트별 스크립트, 제한된 파일 접근에 적합하다. | stdout 일반 로그가 메시지를 깨뜨릴 수 있다. | stderr 로그, 짧은 타임아웃, 프로젝트 경로 제한을 둔다. |
| Streamable HTTP | 팀 공용 서버, SaaS 연동, 여러 클라이언트 연결에 적합하다. | 인증, Origin 검증, 세션 관리가 필요하다. | OAuth, TLS, 라우팅 제한, 감사 로그를 강제한다. |
| SSE | 기존 서버와의 호환 검토에만 제한적으로 본다. | 새 구축의 기본값으로 두기 어렵다. | 가능하면 HTTP 전송으로 전환 계획을 둔다. |
| 커스텀 전송 | 특수 런타임이나 내부 게이트웨이가 필요한 경우만 본다. | 클라이언트 호환성과 보안 검증이 복잡하다. | 표준 전송을 먼저 배제한 근거를 남긴다. |
팀 공용 MCP 서버 구축은 HTTP가 편해 보이지만 보안 설계가 끝나기 전에는 로컬 stdio 파일럿이 더 낫다.
원격 HTTP 서버의 보안 게이트
MCP 전송 규격은 Streamable HTTP 서버가 Origin 헤더를 검증해야 DNS rebinding 공격을 줄일 수 있다고 경고한다.
같은 보안 안내는 로컬 서버가 모든 네트워크 인터페이스에 바인딩되는 구성을 피하라고 권고한다.
Authorization 규격은 HTTP 기반 전송에서 OAuth 계열 메타데이터와 토큰 검증 흐름을 다룬다.
- Origin 검증: 허용된 클라이언트 도메인과 로컬 개발 출처만 통과시킨다.
- localhost 바인딩: 로컬 테스트 서버는 127.0.0.1에 묶고 0.0.0.0 공개를 막는다.
- OAuth 메타데이터: 원격 서버는 인증 서버와 리소스 메타데이터를 문서화한다.
- 토큰 범위: 서버 전체 토큰보다 도구별 scope와 만료 시간을 둔다.
- 동적 등록: 클라이언트 등록을 열어둘 때 redirect URI와 사용자 동의를 별도로 검증한다.
- 감사 로그: 승인 ID, 사용자 ID, 도구명, 입력 해시, 응답 상태를 함께 남긴다.
이 게이트가 없으면 MCP 서버는 편리한 연결 포트가 아니라 내부 시스템을 대신 눌러주는 대리자가 된다.
도구 설계는 읽기 전용부터 시작한다
MCP 서버의 tools는 모델이 상황에 따라 호출하므로 서버 쪽 입력 검증이 마지막 방어선이다.
도구 설명은 모델이 읽는 API 계약이므로 모호하게 쓰면 원하지 않는 호출이 늘어난다.
각 도구는 한 가지 작업만 맡기고 쓰기 작업은 사람 승인과 롤백 기준을 따로 둬야 한다.
| 도구 유형 | 예시 | 기본 정책 | 통과 기준 | 금지 신호 |
|---|---|---|---|---|
| 읽기 전용 | 문서 검색, 이슈 조회, 로그 요약 | 허용하되 로깅한다. | 민감 필드 마스킹이 있다. | 전체 DB 덤프를 반환한다. |
| 쓰기 작업 | 티켓 생성, PR 생성, 설정 변경 | 사람 승인을 요구한다. | 승인자와 롤백 ID가 남는다. | 모델 판단만으로 실행된다. |
| 외부 전송 | 메일 초안, 웹훅 호출, SaaS 등록 | 파일럿에서는 차단한다. | 도메인 allowlist가 있다. | 임의 URL로 요청한다. |
| 비용 발생 | 검색 API, 빌드 실행, 클라우드 작업 | 예산 한도를 둔다. | 월 예산과 호출 제한이 있다. | 무제한 반복 호출이 가능하다. |
MCP 서버 구축 초기에는 도구 수를 늘리는 팀보다 거절 조건을 잘 만든 팀이 더 빨리 승인받는다.
실무 시나리오 1: 이슈 트래커와 코드 저장소 연결
개발팀은 이슈를 읽고 관련 파일을 찾는 작업부터 MCP로 묶고 싶어 한다.
이 경우 서버는 티켓 읽기와 저장소 검색을 분리하고 PR 생성은 별도 승인 도구로 남겨야 한다.
- 이슈 본문은 읽기 전용 resource 또는 read tool로 제공한다.
- 저장소 검색은 파일 경로, 브랜치, 결과 개수를 제한한다.
- PR 생성은 초안 브랜치까지만 만들고 병합 권한은 주지 않는다.
- 비공개 이슈 제목과 고객 식별자는 응답 전에 마스킹한다.
- 도구 호출 로그는 이슈 번호, 저장소, 사용자, 승인 ID를 기준으로 묶는다.
이 조건에서는 MCP 서버 구축의 목표를 자동 병합이 아니라 조사 시간을 줄이는 읽기 전용 보조로 잡는 편이 안전하다.
실무 시나리오 2: 모니터링 대시보드 연결
운영팀은 장애 알림이 오면 AI가 로그와 메트릭을 같이 읽어 원인 후보를 정리하길 원한다.
이 경우 원문 로그 전체를 넘기기보다 기간, 서비스, 심각도, trace ID 기준으로 조회 범위를 줄여야 한다.
- 최근 30분 같은 기본 시간 범위를 강제하고 사용자가 넓힐 때 승인을 받는다.
- 로그 결과는 원문 전체보다 오류 코드, 샘플, 집계값, 링크를 우선 반환한다.
- 개인정보와 세션 토큰은 수집 전 또는 응답 직전에 제거한다.
- 장애 대응 중 쓰기 도구는 알림 생성이나 티켓 업데이트 같은 낮은 위험 작업부터 연다.
- 반복 조회가 비용을 만들 수 있으므로 호출 제한과 캐시 정책을 둔다.
이 조건에서는 MCP 서버가 장애 대응 속도를 높일 수 있지만 로그 비용과 보안 노출도 같이 커진다.
실무 시나리오 3: 사내 문서 검색 서버
문서 검색 MCP 서버는 첫 파일럿으로 좋아 보이지만 권한 상속 문제가 자주 생긴다.
문서 시스템에서 사용자가 볼 수 없는 페이지를 서버 계정이 대신 읽으면 검색 결과만으로도 권한 우회가 된다.
- 사용자별 문서 권한을 서버에서 재검증하거나 클라이언트의 사용자 컨텍스트를 안전하게 전달한다.
- 검색 결과에는 본문 전체보다 제목, 짧은 요약, 접근 가능한 링크를 먼저 반환한다.
- 인사, 법무, 고객지원 문서는 파일럿 범위에서 제외하고 별도 승인 흐름을 만든다.
- RAG 색인과 원본 문서 권한이 어긋나는지 매일 샘플링 검사한다.
- 문서 삭제나 권한 변경이 색인에 반영되는 지연 시간을 운영 지표로 둔다.
이 조건에서는 MCP 서버 구축보다 권한 동기화와 색인 무효화가 더 어려운 작업이 된다.
비용과 운영 기준
MCP 서버 비용은 서버 인프라보다 도구가 호출하는 하위 시스템에서 커질 때가 많다.
검색 API, 로그 조회, 빌드 실행, 외부 SaaS 호출은 모델이 반복 요청하면 사용량이 빠르게 늘어난다.
운영 기준은 월 예산, 호출 제한, 타임아웃, 결과 크기 제한, 장애시 차단 스위치까지 포함해야 한다.
| 항목 | 측정 지표 | 기본 한도 | 초과 시 조치 |
|---|---|---|---|
| 도구 호출량 | 사용자별 호출 수와 서버별 호출 수 | 파일럿 기간 하루 200회 이하 | 도구 비활성화 후 로그 분석 |
| 하위 API 비용 | 검색 API, 로그 조회, 빌드 실행 비용 | 월 예산 70% 알림 | 쓰기 도구와 비용 도구 차단 |
| 응답 크기 | 결과 문자 수와 첨부 링크 수 | 도구당 8,000자 이하 | 요약 모드와 페이지네이션 적용 |
| 지연 시간 | p95 tool latency | 20초 이하 | 타임아웃과 캐시 전략 검토 |
| 오류율 | 도구 오류와 권한 거부 비율 | 5% 초과 경고 | 입력 스키마와 권한 정책 수정 |
MCP 서버 구축 파일럿이 성공했다면 다음 질문은 기능 확대가 아니라 비용 한도 안에서 같은 품질이 유지되는지다.
보안·운영 정책 스켈레톤
아래 YAML은 실제 배포 설정이 아니라 MCP 서버 승인 문서에 넣을 정책 스켈레톤이다.
# mcp-tool-review.yaml
# 목적: MCP 서버 구축 전 도구별 권한, 비용, 감사 기준을 승인 표로 만든다.
server: internal-knowledge
owner: platform-ai-team
transport: stdio
pilot_scope:
users: 5
repositories: ["docs-runbook"]
duration_days: 14
approval:
read_only_tools:
default: allow_with_logging
write_tools:
default: require_human_approval
external_network:
default: block_until_reviewed
security:
secret_source: managed_secret_store
stdout_logging: forbidden_for_stdio
pii_redaction: required_before_response
prompt_injection_scan: required_for_external_content
operations:
max_tool_timeout_seconds: 20
max_result_chars: 8000
audit_fields: [user_id, tool_name, input_hash, approval_id, latency_ms, result_status]
cost:
monthly_budget_owner: finops
stop_condition: "tool calls exceed baseline by 200 percent for 2 consecutive days"
rollback:
disable_server: remove_from_client_config
revoke_tokens: rotate_service_account
preserve_logs_days: 90아래 스크립트는 stdio 서버가 일반 로그를 stdout에 쓰지 않는지 확인하는 간단한 사전 점검 예시다.
#!/usr/bin/env bash
# mcp-smoke-test.sh
# 목적: 실제 업무 서버 등록 전 최소 동작과 실패 조건을 점검한다.
set -euo pipefail
python -m py_compile server.py
uv run python server.py 1>/tmp/mcp-stdout.log 2>/tmp/mcp-stderr.log &
SERVER_PID=$!
sleep 2
kill "$SERVER_PID" || true
if [ -s /tmp/mcp-stdout.log ]; then
echo "FAIL: stdio server wrote non-protocol logs to stdout"
exit 1
fi
if grep -E "token|password|secret" /tmp/mcp-stderr.log; then
echo "FAIL: possible secret in stderr log"
exit 1
fi
echo "PASS: local syntax and logging guard checked"도입을 보류해야 하는 신호
- 서버 하나가 문서 검색, DB 조회, 티켓 생성, 배포 실행을 모두 맡는다.
- 도구 입력 검증을 모델 프롬프트에만 맡기고 서버 코드에서 다시 막지 않는다.
- stdio 서버가 stdout에 일반 로그를 출력한다.
- 원격 HTTP 서버가 Origin 검증 없이 사내 네트워크에서 열린다.
- 서비스 계정 토큰이 클라이언트 설정 파일이나 저장소에 평문으로 들어간다.
- 쓰기 도구가 승인 ID나 롤백 절차 없이 실행된다.
- 감사 로그에 입력 해시와 결과 상태가 남지 않는다.
- 비용 발생 도구에 월 예산과 호출 제한이 없다.
이 신호가 두 개 이상이면 MCP 서버 구축을 중단하고 권한 설계부터 다시 쓰는 편이 낫다.
최종 판단: 데모보다 통제 표가 먼저다
MCP 서버 구축은 빠르게 시작할 수 있지만 운영에 올리는 순간 AI에게 내부 시스템의 손잡이를 달아주는 일이 된다.
첫 파일럿은 읽기 전용 stdio 서버, 제한된 사용자, 제한된 문서 범위, 짧은 보관 로그로 끝까지 검증하는 편이 좋다.
원격 HTTP 서버는 인증, Origin 검증, 토큰 scope, 감사 로그, 예산 한도, 차단 스위치가 준비된 뒤에 열어야 한다.
가장 현실적인 성공 기준은 모델이 멋진 작업을 했는지가 아니라 위험한 입력을 거절하고 실패 로그를 남겼는지다.
함께 보면 좋은 글
AI 에이전트 데이터 유출 방지 2026, 검색 로그·MCP 도구 통제 기준
Insane Search 2026, Claude Code 플러그인 도입 전 보안·운영 기준
AI 에이전트 루프 설계 2026, 검증·트리거·사람 승인 기준
AI 에이전트 프레임워크 2026, LangChain·LlamaIndex·OpenAI Agents 도입 기준
OpenAI Codex 사용법 2026, 설치·CLI·IDE 첫 작업 가이드자주 묻는 질문
MCP 서버 구축은 무엇부터 시작해야 하나요?
읽기 전용 도구 하나와 로컬 stdio 서버부터 시작하는 편이 안전하다.
MCP 서버를 바로 HTTP로 열어도 되나요?
팀 공용 운영에는 HTTP가 필요할 수 있지만 인증, Origin 검증, 감사 로그가 먼저 준비돼야 한다.
stdio 서버에서 가장 자주 나는 실수는 무엇인가요?
일반 로그를 stdout에 출력해 JSON-RPC 메시지를 깨뜨리는 실수가 흔하다.
MCP 도구에 쓰기 권한을 줘도 되나요?
파일럿에서는 보류하고, 필요하면 사람 승인과 롤백 ID가 있는 도구만 제한적으로 열어야 한다.
MCP 서버 구축 비용은 어디서 늘어나나요?
서버 비용보다 검색 API, 로그 조회, 빌드 실행, 외부 SaaS 호출 같은 하위 시스템 비용이 커질 수 있다.
사내 문서 검색 MCP는 안전한가요?
문서 권한과 색인 권한이 맞지 않으면 권한 우회가 생기므로 사용자별 접근 검증이 필요하다.
출처와 확인일
- Model Context Protocol — What is the Model Context Protocol? (확인일: 2026-06-29)
- Model Context Protocol — Build an MCP server (확인일: 2026-06-29)
- Model Context Protocol Specification — Transports (확인일: 2026-06-29)
- Model Context Protocol Specification — Authorization (확인일: 2026-06-29)
- Model Context Protocol — Security Best Practices (확인일: 2026-06-29)
- Anthropic Claude Code Docs — Connect Claude Code to tools via MCP (확인일: 2026-06-29)
- GitHub — modelcontextprotocol/python-sdk (확인일: 2026-06-29)
- GitHub — modelcontextprotocol/typescript-sdk (확인일: 2026-06-29)
이 글은 공개 기술 문서와 벤더 자료를 바탕으로 한 일반 정보이며 실제 명령, 인증 방식, 가격, 지원 기능은 버전과 제품 정책에 따라 달라질 수 있다.
운영 적용 전에는 공식 문서, 보안팀 검토, 법무 검토, 비용 승인, 장애 대응 절차를 함께 확인해야 한다.
댓글
댓글 쓰기