microsoft/mcp-gateway

MCP Gateway – 무엇인가

MCP Gateway는 **Model Context Protocol (MCP)**를 위해 구축된 오픈 소스 역방향 프록시(reverse-proxy) 및 관리 계층입니다. Kubernetes 클러스터에서 실행되며 두 가지 주요 평면(plane)을 제공합니다:

• Control plane – MCP 서버 인스턴스(이하 adapters) 및 추가 기능을 제공하는 tools를 생성, 업데이트, 목록 조회 및 삭제할 수 있는 REST API 세트입니다. 또한 Azure Cognitive Services 엔드포인트를 제공하는 경우 agents 및 sessions (LLM 기반 워크플로우)를 선택적으로 관리할 수 있습니다.
• Data plane – 들어오는 MCP 트래픽을 적절한 서버로 라우팅하는 상태 비저장(stateless) 역방향 프록시입니다. session-aware routing (동일한 session_id를 가진 모든 요청이 동일한 pod로 이동) 및 도구 호출을 올바른 도구 컨테이너로 동적으로 전달하는 Tool Gateway Router를 제공합니다.

이 게이트웨이는 엔터프라이즈 배포를 위해 설계되었습니다. Bearer-token 인증 및 역할 기반 액세스 제어(RBAC)를 위해 Azure Entra ID와 통합되며, 내장된 React 관리 포털을 제공하고, Docker/Kubernetes를 사용하여 로컬에서 배포하거나 원클릭 Azure 템플릿으로 배포할 수 있습니다.

---

Core Concepts

Concept	What It Means
MCP Server (Adapter)	Model Context Protocol을 구현하는 컨테이너 – 본질적으로 LLM이 통신할 수 있는 스트리밍 가능한 HTTP 엔드포인트입니다.
Tool	특정 MCP-tool 정의(이름, 입력 스키마, 실행 엔드포인트)를 구현하는 등록된 서비스(컨테이너)입니다.
Tool Gateway Router	게이트웨이 뒤에 위치하는 MCP 서버; 들어오는 MCP 요청을 검사하고, 도구 정의를 조회하여, 호출을 올바른 도구 컨테이너로 전달합니다.
Session-aware routing	동일한 session_id를 가진 모든 호출이 동일한 백엔드 pod에 도달함을 보장하여 상태 유지 상호작용을 보존합니다.
Agents & Sessions (preview)	등록된 도구를 호출할 수 있는 선택적 LLM 기반 에이전트(및 몇 가지 내장 bash/file 도구). 세션은 Server-Sent Events를 통해 이벤트를 스트리밍합니다.

---

Key Features

• RESTful control-plane API를 사용하여 adapters, tools, agents, sessions를 관리합니다 (CRUD, 상태, 로그).
• Authentication & RBAC를 Azure Entra ID를 사용하여 수행합니다 (읽기/쓰기 역할 mcp.admin, mcp.engineer 등).
• Stateless reverse proxy를 사용하여 생산성 수준의 확장이 가능합니다 (분산 세션 스토어 포함).
• Dynamic tool routing – 도구를 한 번 등록하면 라우터가 자동으로 호출을 해당 도구로 직접합니다.
• Built-in management portal (/portal/)를 통해 시각적 CRUD, 로그 검사, 브라우저 내 JSON-RPC 테스트 콘솔을 제공합니다.
• Kubernetes-native deployment (StatefulSets, headless services) 및 간단한 로컬 Docker-K8s 배포 경로를 제공합니다.
• Optional LLM agents를 통해 도구를 호출하고 내장 bash/file 유틸리티를 사용할 수 있으며, sandbox-style 안전 제한이 적용됩니다.
• Support for both local and remote MCP servers – 기존 MCP 엔드포인트를 프록시할 수 있습니다.

---

Typical Use Cases

1. Enterprise AI platform – 인증, 라우팅, 생명주기 관리를 단일 게이트웨이 뒤에서 처리하는 많은 MCP-compatible LLM 백엔드(예: Copilot, 커스텀 모델)를 호스팅합니다.
2. Tool-as-a-service – 도메인 특화 도구(날씨, 금융, 코드 실행)를 한 번 등록하여 MCP 클라이언트가 엔드포인트를 하드코딩 없이 호출할 수 있게 합니다.
3. Multi-tenant development sandbox – 개발자가 API를 통해 격리된 adapters/tools를 생성하여 로컬에서 테스트하고 프로덕션 환경으로 승격시킨다.
4. LLM-driven agents – 여러 도구를 오화화하는 에이전트(예: 데이터 조회, 스크립트 실행, 파일 쓰기)를를 생성하고 VS Code의 Copilot chat을 통해 노출출합니다.
5. Observability & governance – 규제 환경에서 모든 MCP 트래픽에 대한 로그, 텔레메트리, 역할 기반 액세스 제어를 중앙 집중화합니다.

---

Quick-Start Summary (Local)

1. Prerequisites – .NET 8 SDK, Docker Desktop (Kubernetes 포함), 로컬 Docker registry를 설치합니다.
2. Build images – 샘플 MCP server와 샘플 tool을 컴파일하여 localhost:5000에 push합니다.
3. Publish gateway images – 제공된 publish profile을 사용하여 dotnet publish를 실행하여 gateway와 tool-router 컨테이너를 생성합니다.
4. Deploy – deployment/k8s/local-deployment.yml을 적용하고 서비스를 포 포워딩합니다 (kubectl port-forward … 8000:8000).
5. Create an adapter – /adapters로 JSON { "name": "mcp-example", "imageName": "mcp-example", "imageVersion": "1.0.0" }을 POST 합니다.
6. Register a tool | POST /tools로 도구 정의(예: 날씨 도구)와 컨테이너 이미지를 함께 보냅니다.
7. Connect a client – VS Code의 MCP config를 http://localhost:8000/adapters/<name>/mcp로 설정하여 직접 서버 액세스하거나, http://localhost:8000/mcp로 설정하여 도구 라우팅을 사용합니다.
8. (Optional) Enable agents – Azure Cognitive Services 엔드포인트를 포함한 FoundrySettings 블록을 추가하고 /agents 및 /sessions API를를 통해 에이전트/세션을 생성합니다.

---

Where to Find More

• OpenAPI spec – openapi/mcp-gateway.openapi.json (Postman, Swagger UI 등에 임포트 가능)
• Management portal source – portal/README.md
• Entra ID role configuration guide – docs/entra-app-roles.md
• Sample server implementations – sample-servers/mcp-example/ 및 sample-servers/tool-example/
• Azure deployment guide – 원클릭 템플릿과 Entra ID 설정 단계를 포함한 "Deploy to Azure" 섹션.

---

Bottom line: MCP Gateway는 모든 Model Context Protocol 서비스에 대해 프로덕션 수준의, Kubernetes-native한 외형을 제공하며, 인증, 세션-affinity, 동적 도구 라우팅, 그리고 선택적 LLM-agent 오케스트레이션까지—모두 깔끔한 REST API와 준비된 UI를 통해 처리합니다.