MCP (Model Context Protocol) 서버를 사용하기 시작하면 곧 어떤 문제에 부딪히게 됩니다. 서버가 늘어날수록 클라이언트 측의 설정이 눈덩이처럼 불어난다는 점입니다.

GitHub용, Slack용, 사내 DB용, 메모리용…… 이렇게 서버를 추가하다 보면 Claude Code, Claude Desktop, Cursor 각각의 설정 파일에 동일한 서버 정의를 반복해서 작성하게 됩니다. 에이전트(M개)와 서버(N개)의 조합은 M×N으로 불어나며, 인증 정보도 곳곳에 흩어지게 됩니다.

이 기사에서는 그 M×N 문제를 M+1+N으로 간략화하는 OSS인 MCP 게이트웨이 MCPX (Lunar.dev 제작 · MIT 라이선스)를 Docker로 셀프 호스팅하여 Claude Code에서 사용하는 방법까지 핸즈온으로 해설합니다.

대상 독자: 여러 개의 MCP 서버를 운용하고 있으며, 설정 중복이나 액세스 제어에 어려움을 겪고 있는 엔지니어
목표: 로컬에 MCPX를 구축하여, 여러 상류(upstream) MCP 서버를 하나의 엔드포인트로 집약하고, tool 단위의 액세스 제어를 설정할 수 있는 상태를 만드는 것
전제 조건: Docker가 동작하는 환경 (Docker Desktop도 가능)

본 기사의 커맨드 및 설정은 공식 문서와 GitHub 리포지토리 (

TheLunarCompany/lunar

)의 기재 내용을 바탕으로 합니다. MCPX는 활발하게 업데이트되고 있으므로, 버전이나 엔드포인트 경로는 공식 Docs와 Control Plane UI의 표시를 최종적인 정답으로 간주해 주십시오.

• MCPX는 여러 상류 MCP 서버를 집약하는 MCP 서버 (Aggregator)입니다. 에이전트는 단 1개의 연결만 가지면 됩니다.
• docker run 한 번으로 기동됩니다. 포트는 **9000(본체) / 5173(관리 UI) / 3000(메트릭스)**입니다.
• 설정은 2개의 파일로 구성됩니다. app.yaml로 상류 서버를 정의하고, mcp.json으로 인증·권한·tool 그룹을 정의합니다.
• permissions.base: "block"을 기점으로, consumer(이용자)별로 사용할 수 있는 tool을 제한하는 거버넌스가 표준으로 탑재되어 있습니다.
• Claude Code / Claude Desktop / Cursor 등 MCP 호환 클라이언트로부터 하나의 URL로 모든 tool에 액세스할 수 있습니다.

MCP 서버를 클라이언트에 직접 연결하는 구성에서는 에이전트의 수 M과 서버의 수 N의 곱만큼 연결·설정·인증 정보가 필요하게 됩니다.

게이트웨이를 하나 사이에 두면, 각 에이전트는 게이트웨이로의 1개 연결만 가지며, 게이트웨이가 상류의 N개 서버를 묶어줍니다. 연결의 총수는 M + 1 + N (에이전트 M개 + 게이트웨이 + 서버 N개)으로 수렴하여, 조합 폭발이 사라집니다.

MCPX는 이 게이트웨이 계층을 OSS로 제공하며, tool 단위의 액세스 제어 · 이용자 식별 · 감사 로그 · 인증 정보의 격리를 표준으로 갖추고 있습니다.

먼저 설정 파일을 둘 디렉토리를 만듭니다. MCPX는 이 디렉토리에서 app.yaml과 mcp.json을 찾으러 갑니다.

mkdir mcpx-config
cd mcpx-config

Docker가 동작하고 있는지 확인합니다.

docker version

공식 Quick Start 커맨드로 MCPX를 기동합니다. MCPX는 상류 서버를 Docker로 기동하기 때문에 --privileged (Docker-in-Docker)가 필요합니다.

docker run --rm --pull always --privileged \
-v ./:/lunar/packages/mcpx-server/config \
-p 9000:9000 -p 5173:5173 -p 3000:3000 \
...

공개되는 포트의 역할은 다음과 같습니다.

공개되는 포트의 역할은 다음과 같습니다.

--privileged는 강력한 권한을 부여하는 플래그입니다. 실제 운영 환경에서는 Kubernetes용 구성(공식 Docs에 전용 가이드 있음)이나, 신뢰할 수 있는 네트워크 내부에서의 운용을 검토해 주세요. 개인 테스트에서는 문제가 없지만, 무조건 프로덕션 환경으로 가져가지는 않도록 주의해야 합니다.

MCPX가 묶는 상위 서버들은 mcp.json에 작성합니다. 시작 시 이 파일을 읽어 각 서버를 MCPX 프로세스 내에서 구동합니다.

mcpx-config/mcp.json을 생성하고, 예시로 memory(영구 메모리)와 time(시간) 두 가지를 등록합니다.

{
"mcpServers": {
"memory": {
...

각 서버의 필드는 다음과 같습니다.

참고로, 서버의 식별명은 mcpServers의 키 이름(위 예시에서는 `

설정 후에는 클라이언트를 재시작합니다. 이렇게 하면 Claude Code에서는 mcpx라는 단 하나의 서버만 보이게 되며, 그 이면에는 memory · time · (추가한 만큼의) GitHub · Slack……과 같은 상위 tool들이 모두 연결됩니다.

연결용 엔드포인트(Endpoint)의 정확한 경로는 MCPX의 버전에 따라 달라질 수 있습니다.

http://localhost:5173/ 의 Control Plane UI에 표시되는 연결 스니펫(Snippet)을 복사하는 것이 가장 확실합니다. Claude Desktop · Cursor · VSCode · n8n · CrewAI · LangChain 등 다른 MCP 호환 클라이언트에서도 동일한 방식으로 1개의 연결로 집약할 수 있습니다.

실제로 구축할 때 빠지기 쉬운 주의 사항을 정리해 둡니다.

MCPX를 사용하면 어지럽게 널려 있는 MCP 서버군을 하나의 게이트웨이 뒤로 숨겨, 클라이언트 설정의 중복 · 인증 정보의 분산 · 액세스 제어(Access Control)의 부재라는 세 가지 고통을 한꺼번에 해결할 수 있습니다.

• mcp.json으로 상위 서버를 집약하여, 에이전트는 단 하나의 연결만 가짐 (M+1+N)
• app.yaml의 base: "block" + toolGroups를 통해 업무 단위의 권한을 게이트웨이에 집중
• OSS (MIT)이므로 셀프 호스팅이 가능하며, 인증 정보를 클라이언트 외부에 격리할 수 있음

MCP 서버가 3개를 넘어가는 시점부터 게이트웨이 도입의 비용 대비 효과는 급격히 상승합니다. 우선은 memory + time 두 가지를 묶는 것부터 직접 시도해 보세요.

• MCPX (GitHub · TheLunarCompany/lunar): https://github.com/TheLunarCompany/lunar
• MCPX README: https://github.com/TheLunarCompany/lunar/blob/main/mcpx/README.md
• 공식 Docs (Quick Start): https://docs.lunar.dev/mcpx/get_started/
• mcp.json 사양: https://docs.lunar.dev/mcpx/mcp.json/
• 액세스 제어 설계 (공식 블로그): https://www.lunar.dev/post/mcp-gateway-access-controls-defining-permissions-for-llm-agents