Azure Container Apps를 사용한 원격 Model Context Protocol (MCP) 서버 구축 가이드

이 가이드는 Azure Container Apps를 사용하여 원격 Model Context Protocol (MCP) 서버를 설정하기 위한 기본적인 구성 요소를 제공하는 빠른 시작 가이드입니다. MCP 서버는 Node.js 및 TypeScript를 사용하여 구축되었으며, 서버리스 (serverless) 환경에서 다양한 도구와 서비스를 실행하는 데 사용할 수 있습니다. 또한 이 프로젝트는 MCP 서버 엔드포인트와 도구를 보호하기 위해 JWT 기반 인증과 역할 기반 액세스 제어 (RBAC)를 결합한 다층 보안 아키텍처를 구현합니다.

경고

여기에 제시된 코드는 데모 목적으로만 제공됩니다. 귀하의 특정 시나리오(기업 내부 규칙, 특정 보안 제어 또는 기타 보호 메커니즘 포함)는 이 저장소에 설명된 내용과 다를 수 있습니다. 인증 및 인가 (authorization)가 필요한 모든 운영 환경 및 고객 대상 자산에 대해서는 항상 보안 감사와 위협 모델링 (threat modeling)을 수행하십시오.

Model Context Protocol (MCP)는 대규모 언어 모델 (LLMs)이 외부 도구 및 서비스와 표준화된 방식으로 상호 작용할 수 있도록 하는 개방형 프로토콜입니다. MCP를 통해 LLM은 데이터베이스, API 및 기타 서비스와 같은 다양한 리소스에 액세스하고 활용하여 능력을 향상시키고 더욱 정확하고 관련성 높은 응답을 제공할 수 있습니다.

다음은 일반적인 MCP 서버 설정에 대한 아키텍처 다이어그램입니다:

flowchart TD
user(("fa:fa-users User"))
host["VS Code, Copilot, LlamaIndex, Langchain..."]
...

Azure Container Apps는 컨테이너화된 애플리케이션의 배포 및 운영을 단순화하는 완전 관리형 서버리스 (serverless) 컨테이너 플랫폼입니다. ACA는 또한 서버리스 GPU 지원을 제공하므로, 사용자가 직접 컨테이너를 가져와 수요에 따라 자동으로 확장되는 GPU 지원 환경에 배포할 수 있습니다.

주요 이점:

• 자동 확장 (Autoscaling) – 유휴 상태 시 0으로 확장 (scale to zero), 사용량에 따라 확장 (scale out)

• 초 단위 과금 (Pay-per-second billing) – 사용한 컴퓨팅 자원에 대해서만 비용 지불

• 사용 편의성 (Ease of use) – 개발 속도를 가속화하고, 어떤 컨테이너든 쉽게 가져와 클라우드의 GPU에서 실행 가능

• 인프라 관리 불필요 (No infrastructure management) – 모델과 앱에만 집중

• 엔터프라이즈급 기능 (Enterprise-grade features) – 사용자 정의 가상 네트워크 (virtual networks), 관리 ID (managed identity), 프라이빗 엔드포인트 (private endpoints) 등을 즉시 지원하며 완전한 데이터 거버넌스 제공

• 최신 버전의 VS Code 설치

• GitHub Copilot 및 GitHub Copilot Chat 확장 프로그램 설치

MCP 서버를 로컬에서 실행하는 것을 선호한다면, 다음 단계에 따라 수행할 수 있습니다.

로컬 머신에 다음 도구들이 설치되어 있어야 합니다:

필수 구성 요소가 설치되면, 다음 단계에 따라 MCP 서버를 로컬에서 실행할 수 있습니다:

• 이 리포지토리 (repository)를 클론(Clone)합니다:

git clone https://github.com/Azure-Samples/mcp-container-ts
cd mcp-container-ts

• 프로젝트 의존성 (dependencies) 설치

npm install

• 새로운 JWT 설정 생성:

npm run generate-token -- --admin

참고

--admin, --user 또는 --readonly 플래그를 사용하여 다른 역할 (role)을 가진 토큰을 생성할 수도 있습니다. 생성된 토큰은 선택한 역할에 따라 서로 다른 권한을 갖게 됩니다 (자세한 내용은 src/auth/authorization.ts를 참조하세요).

이 작업은 프로젝트 루트의 .env 파일에 새로운 JWT 설정을 추가(또는 생성)합니다. 생성된 토큰은 MCP 서버에 대한 요청을 인증하는 데 사용됩니다.

중요

프로덕션 환경에서는 비밀값(secrets)과 토큰을 관리하기 위해 더 보안이 강화된 방법을 사용해야 합니다.

• 개발 서버 시작

npm run dev

터미널에 다음과 같은 출력이 표시되어야 합니다:

mcp:db 2025-07-23T16:48:05.381Z PRAGMA journal_mode = WAL +0ms
mcp:db 2025-07-23T16:48:05.382Z CREATE TABLE IF NOT EXISTS todos (
mcp:db id INTEGER PRIMARY KEY AUTOINCREMENT,
...

• MCP 서버에 접속하고 사용하려면, 아래의 'MCP 서버 사용하기 (Use your MCP server)' 섹션을 읽어보세요.

참고

애플리케이션이 시작될 때, 서버는 인메모리 SQLite 데이터베이스를 생성합니다. 이 데이터베이스는 도구(tools)의 상태와 MCP 서버와의 상호작용을 저장하는 데 사용됩니다.

MCP 서버를 Azure Container Apps에 배포하려면 Azure Developer CLI (azd)를 사용할 수 있습니다. 이를 통해 최소한의 노력으로 프로젝트를 Azure에 프로비저닝(provision)하고 배포할 수 있습니다.

• Azure Developer CLI를 설치합니다.

필수 구성 요소가 설치되면, 다음 단계에 따라 MCP 서버를 Azure Container Apps에 배포할 수 있습니다:

• 이 리포지토리(repository)를 클론(Clone)합니다.

git clone https://github.com/azure-samples/mcp-container-ts.git
cd mcp-container-ts

• Azure 계정에 로그인합니다.

azd auth login

GitHub Codespaces 사용자의 경우, 이전 명령이 실패하면 다음을 시도하세요:

azd auth login --use-device-code

• 프로젝트를 프로비저닝 및 배포합니다 (이 명령을 실행할 때 클론한 리포지토리 폴더 안에 있는지 확인하세요):

azd up

• 배포가 완료되면 출력된 URL을 사용하여 MCP 서버에 접속할 수 있습니다. URL은 다음과 같은 형태입니다:

https://<env-name>.<container-id>.<region>.azurecontainerapps.io

• MCP 서버에 접속하고 사용하려면, 아래의 'MCP 서버 사용하기 (Use your MCP server)' 섹션을 읽어보세요.

참고

단순히 배포를 테스트 중이었다면, 비용이 발생하지 않도록 다음 명령을 실행하여 배포된 모든 리소스를 제거하고 정리할 수 있습니다:

azd down --purge --force

이 템플릿을 시작하는 몇 가지 다른 옵션이 있습니다. 가장 빠르게 시작하는 방법은 GitHub Codespaces를 사용하는 것입니다. 모든 도구를 자동으로 설정해주며 브라우저에서 MCP 서버를 실행할 수 있기 때문입니다.

GitHub Codespaces를 사용하여 이 템플릿을 가상으로 실행할 수 있습니다. 버튼을 누르면 브라우저에서 웹 기반 VS Code 인스턴스가 열립니다:

템플릿을 엽니다 (몇 분 정도 걸릴 수 있습니다):

터미널 창을 엽니다

MCP 서버를 로컬에서 실행하거나 Azure Container Apps에 배포하기 위한 다음 단계로 진행합니다.

참고

GitHub Codespaces 내부에서 MCP 서버를 실행하는 경우, 포트 가시성(Port visibility)을 Public으로 변경해야 합니다: "PORTS" 탭 클릭 → 열려 있는 포트(기본값 3000) 우클릭 → Port visibility → Public 선택.

관련된 옵션으로 VS Code Dev Containers가 있습니다. 이는 Dev Containers 확장을 사용하여 로컬 VS Code에서 프로젝트를 엽니다:

아직 설치되지 않았다면 Docker Desktop과 VS Code Dev Containers 확장을 설치합니다.

Docker Desktop을 시작합니다 (설치되어 있지 않다면 설치하십시오).

프로젝트를 엽니다:

터미널 창을 엽니다.

MCP 서버를 로컬에서 실행하거나 Azure Container Apps에 배포하기 위한 다음 단계로 진행합니다.

이 리포지토리에는 OpenAI 모델과 MCP 서버를 사용하는 방법을 보여주는 예제가 포함되어 있습니다. 예제는 [examples/](./examples/) 디렉토리에 위치합니다.

MCP 서버에 연결하는 가장 빠른 방법은 제공된 .vscode/mcp.json 설정 파일을 사용하여 VS Code 환경에 MCP 서버를 설정하는 것입니다. 이 설정 파일에는 URL 및 전송 유형(Transport type)을 포함하여 MCP 서버에 필요한 설정이 들어 있습니다.

{
"inputs": [
{
...

이 파일을 열면, MCP 서버에 연결하고 사용 가능한 도구(Tools)를 가져오는 인라인 액션 버튼인 "start"를 클릭할 수 있습니다.

중요: 서버가 JWT 토큰으로 보안 처리가 되어 있으므로, VS Code에서 토큰을 입력하라는 메시지가 표시됩니다. npm run generate-token 명령으로 생성된 .env 파일에서 "JWT_TOKEN" 값을 복사해야 합니다.

참고

실제 운영 환경에서는 토큰을 검증하고 더 안전한 인증 방법을 사용해야 합니다. 이것은 테스트 목적으로만 사용되는 데모 토큰입니다. 서버 보안에 대해 자세히 알아보려면 여기를 참조하세요.

명령 팔레트(Command palette)에서 MCP Server를 추가하고 실행 중인 서버의 HTTP 엔드포인트(Endpoint)에 URL을 추가합니다:

로컬 개발의 경우, URL은 다음과 같습니다:

http://localhost:3000/mcp

Azure Container Apps의 경우, URL은 다음과 같습니다:

https://<env-name>.<container-id>.<region>.azurecontainerapps.io/mcp

• 추가할 MCP 서버의 유형으로 **HTTP (HTTP 또는 Server-Sent Events (SSE))**를 선택합니다. - 끝에 /mcp 경로를 포함하여 실행 중인 HTTP 엔드포인트의 URL을 입력합니다. - 서버 ID를 입력합니다. (원하는 임의의 이름을 사용할 수 있습니다.)
• 이 서버를 사용자 설정 (User settings, 사용자에게 사용 가능한 모든 앱에서 이용 가능)에서 실행할지, 아니면 워크스페이스 설정 (Workspace settings, 해당 앱에서만 이용 가능)에서 실행할지 선택합니다.
• Copilot 채팅 에이전트 모드에서 도구를 트리거할 프롬프트를 입력합니다. 예: 코드를 일부 선택한 후 다음 프롬프트를 입력합니다.

I need to send an email to Dan, please add that to my todo list.

• 도구 실행 요청이 뜨면, Continue를 클릭하여 승인합니다.

• 완료되면 터미널 창에서 Ctrl+C를 눌러 func.exe 호스트 프로세스를 중지하고, 명령 팔레트(Command palette)에서 List MCP Servers를 선택하여 로컬 서버를 중지합니다.

• 새 터미널 창에서 MCP Inspector를 설치하고 실행합니다.

npm run inspect

• 터미널에 표시된 URL(예: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=xyz)을 CTRL+클릭하여 MCP Inspector 웹 앱을 로드합니다.
• 전송 유형(Transport type)을 Streamable HTTP로 설정합니다. - 인증 헤더(Authentication header)를 Authorization으로 설정하고