간단 요약: Model Context Protocol (MCP) 서버는 API의 기능을 에이전트가 발견하고 호출할 수 있는 도구(tools)로 노출하며, 이는 타입이 지정된 입력 스키마와 모델이 조치할 수 있는 결과를 포함합니다. 기존 HTTP API의 경우, 도구를 직접 작성하는 것보다 OpenAPI 계약을 기반으로 MCP 서버를 구축하는 것이 가장 빠르고 신뢰할 수 있는 방법입니다. 이렇게 해야만 도구가 실제 API에서 벗어나지 않도록 할 수 있습니다. 어려운 부분은 정상적인 경로(happy path)가 아니라 전송(transport), 인증(authentication), 최소 권한 범위 지정(least-privilege scoping), 그리고 의존하는 에이전트를 깨뜨리지 않고 도구를 버전 관리하는 것입니다.
본 가이드는 전체 라이프사이클을 다룹니다. 사양(spec)을 도구로 변환하고, 서버를 어디에 배포할지 선택하며, 보안을 강화하고, 테스트하며, 호스팅된 게이트웨이가 직접 운영하는 프로세스보다 나은 시점을 결정하는 과정입니다. 구체적인 설정 방법은 링크를 따라가 주십시오.
MCP란 무엇이며 함수 호출과 어떻게 다른가
MCP는 AI 모델을 애플리케이션에 각 도구를 하드코딩(hard-coding)하는 대신 외부 도구 및 데이터와 연결하기 위한 표준 프로토콜입니다. 사용 여부를 결정하고 있다면, MCP vs function calling vs plugins부터 시작하여 서버가 노출할 수 있는 세 가지 것(tools vs resources vs prompts)을 도구 대 리소스 대 프롬프트에서 이해해야 합니다. 에이전트 간의 통신과 도구를 호출하는 에이전트의 차이는 A2A vs MCP: agents vs tools에 있습니다.
OpenAPI를 사용하여 MCP 서버 구축하기
각 연산별로 래퍼(wrapper)를 수동으로 작성하는 것은 느리고 API가 변경되는 순간마다 무너지기 쉽습니다. 반복 가능한 방법은 계약(contract)으로부터 서버를 생성하는 것입니다. OpenAPI에서 MCP 서버까지 단계별 가이드, REST API를 MCP 서버로 변환하기에서 직접 매핑하는 방법, 그리고 OpenAPI를 호스팅형 MCP 서버로 만들기의 방법을 참고하십시오. 서버는 수동으로 유지 관리해야 할 프로젝트가 아니라 빌드 아티팩트(build artifact)로 취급해야 합니다. MCP 서버는 빌드 아티팩트입니다에서 워크플로우를 설명합니다.
모든 엔드포인트(endpoint)를 서버에 무작정 노출하는 것은 모델의 제한된 컨텍스트(context)를 낭비하고 에이전트가 절대 호출해서는 안 되는 호출을 유발합니다. 표면적을 의도적으로 범위 지정해야 합니다: 전체 OpenAPI가 아닌 세 가지 연산만 노출하기를 참고하고, 에이전트별로 [모든 것이 아닌 에이전트별로 노출하는 허브]를 구성하며(https://www.powerduck.com/blog/mcp-hub-should-expose-per-agent-not-everything/), MCP 서버가 에이전트 컨텍스트를 낭비하는 경우에서 과도한 노출의 비용을 이해해야 합니다. 계약(contract)이 변경되면 도구 목록(tool list) 역시 함께 변경되어야 합니다. 사양 변경은 MCP 도구 목록 업데이트를 유발해야 합니다.
전송 방식: stdio 대 원격 HTTP (Transport: stdio vs remote HTTP)
단일 사용자에게 로컬 stdio 서버는 간단하지만, 도구를 공유하거나 브라우저에서 실행하거나 중앙 인증이 필요한 경우에는 원격 HTTP 서버가 필요합니다. 비교 내용은 [MCP stdio vs remote HTTP transports]에 있으며, 공유 또는 다중 사용자 도구의 경우 [streamable HTTP beats stdio for shared tools]를 권장합니다.
인증 및 토큰 저장 위치
원격 서버는 실제 인증(real auth)이 필요하며, 자격 증명은 프롬프트나 도구 페이로드에 절대 포함되어서는 안 됩니다. [MCP authentication with OAuth2 for remote servers]로 시작하고, 업스트림 토큰을 MCP JSON 대신 게이트웨이에 보관해야 하며 [upstream token in the gateway, not in MCP JSON], 기본 URL은 중앙에서 고정(pin)해야 합니다 [pin the base URL in the gateway, not the agent prompt].
보안: 최소 권한 원칙 및 프롬프트 주입
노출하는 모든 도구는 에이전트가 시스템에서 작동할 수 있는 새로운 경로이므로, 범위를 엄격하게 제한하고 도구 출력이 악의적인 지침을 포함할 수 있다고 가정해야 합니다. 위협 모델은 [MCP security, prompt injection, and least privilege]에 있으며, 키는 팀 전체와 공유하기보다는 역할별로 범위가 지정되어야 합니다 [scope MCP keys per role, not team-wide]. 또한 전체 URL을 재설정하지 않고도 단일 팀원의 키를 취소할 수 있어야 합니다; [revoke one teammate key, not the whole MCP URL].
자체 구축 서버보다 호스팅 게이트웨이를 사용하는 것이 더 유리한 경우
내부 API 및 여러 업스트림(upstreams)의 경우, 게이트웨이(gateway)가 서비스를 집계하고 인증(auth) 및 속도 제한(rate limits)을 처리하며 에이전트(agents)를 네트워크 토폴로지에서 분리합니다. 이러한 집계 패턴은 내부 API 및 집계를 위한 MCP 게이트웨이에 설명되어 있으며, Node 프로세스를 직접 운영하지 않아도 되는 경우의 예시는 Node 서버가 아닌 호스팅된 MCP 게이트웨이에서 확인할 수 있습니다.
에이전트를 깨뜨리지 않으면서 도구 버전 관리하기
에이전트는 런타임(runtime) 시점에 도구를 발견하며, 해당 도구의 입력 형태(input shapes)에 의존합니다. 따라서 도구 이름을 변경하거나 매개변수를 강화하면 워크플로우가 조용히 깨질 수 있습니다. 안전한 접근 방식은 에이전트를 깨뜨리지 않는 MCP 도구 버전 관리에서 제시합니다.
클라이언트 테스트, 디버깅 및 연결하기
서버를 API를 검증하는 방식과 동일하게 검증할 수 있습니다: 도구 목록을 나열하고, 문서화된 입력으로 호출하며, 결과를 확인합니다. 절차는 MCP 서버 테스트 및 디버깅 방법에 나와 있습니다. 그런 다음 실제로 사용하는 클라이언트를 연결하세요 — Cursor와 Claude Code를 내부 API에 연결하고, MCP 클라이언트 비교: Claude Desktop, Cursor, VS Code, Windsurf, Cline, Zed에서 클라이언트 환경을 비교할 수 있습니다. 배포 시에는 문서(docs)와 서버를 사용자가 제어하는 도메인에 배치해야 합니다. 사용자 지정 도메인에 API 문서 및 MCP 게시.
다음 단계는?
Powerduck은 이 전체 흐름(계약부터 디버그, 테스트, 목업(mock), 그리고 에이전트가 호출할 수 있는 도구까지)을 담고 있는 로컬 우선(local-first), OpenAPI 우선(OpenAPI-first) 작업 공간입니다. Powerduck 홈페이지에서 확인해 보세요.
MCP 서버는 그 뒤에 있는 계약(contract)만큼만 가치가 높습니다. OpenAPI 가이드로 돌아가서 에이전트에게 적절한 컨텍스트를 제공하고 작업 내용을 검증하는 방법을 AI 코딩 에이전트 가이드에서 배우세요.
자주 묻는 질문 (FAQ)
모든 API에 대해 새로운 MCP 서버를 작성해야 하나요? 아닙니다. 각 서버는 해당 OpenAPI 문서를 기반으로 생성하고 게이트웨이(gateway)를 사용하여 통합하세요. 수동으로 작성된 서버는 예외일 뿐 규칙이 아닙니다.
MCP는 AI 코딩 어시스턴트 전용인가요? 처음에는 그랬지만, 내부 기업 시스템을 포함하여 모든 호환 가능한 모델에 도구와 데이터에 대한 통제된 접근 권한을 부여하는 일반적인 방법입니다.
에이전트가 위험한 도구를 호출하는 것을 어떻게 막을 수 있나요? 노출하지 말고, 키를 최소 역할(minimum role)로 범위 지정하고, MCP 계층이 신뢰할 수 없는 것처럼 상위 서비스(upstream service)에서 인증을 강제하세요. 프롬프트 인젝션은 도구 결과(tool results)를 통해 발생할 수 있으므로, 모델 자체의 자율 규제를 절대 믿지 마세요.