MCP Router

로컬 stdio MCP 서버를 명령·작업 설명으로 검색하고 필요한 서버만 실행하는 allowlist 기반 MCP 어댑터입니다.

동작 방식

Codex에는 이 라우터 하나만 상시 등록합니다. 라우터는 작은 고정 도구 5개만 노출하며, 하위 MCP의 전체 도구 스키마는 load_mcp를 명시적으로 호출한 뒤에만 응답으로 반환합니다.

1. search_mcp(query)로 적합한 MCP를 검색합니다.
2. load_mcp(name)으로 하위 프로세스를 시작하고 도구 스키마를 받습니다.
3. call_mcp(name, tool_name, arguments)로 실제 도구를 호출합니다.
4. 작업 후 unload_mcp(name)으로 프로세스를 종료합니다.

추가로 list_mcp()는 등록 목록과 현재 로드 상태를 반환합니다.

보안 경계

• 모델이 레지스트리를 수정하는 도구는 제공하지 않습니다.
• registry.yaml에 등록된 절대 실행 파일만 시작합니다.
• 셸 문자열을 실행하지 않고 command와 args 배열을 직접 전달합니다.
• 기본 시스템 환경변수 외에는 env와 inherit_env에 선언된 값만 전달합니다.
• 비밀 값은 YAML에 저장하지 않고 inherit_env에 환경변수 이름만 등록합니다.
• 하위 MCP의 도구 이름도 로드 시 확인된 목록으로 제한합니다.

설치 및 검증

cd <mcp-router-directory>
uv sync
uv run pytest
uv run ruff check .

실행

uv run mcp-router

Codex 등록

Codex 설정에는 하위 MCP 대신 라우터만 추가합니다.

[mcp_servers.mcp_router]
command = "C:\\path\\to\\mcp-router\\.venv\\Scripts\\mcp-router.exe"
cwd = "C:\\path\\to\\mcp-router"

레지스트리 확장

registry.example.yaml을 registry.local.yaml로 복사한 뒤 servers 아래에 항목을 추가합니다. registry.local.yaml은 Git에서 제외됩니다.

servers:
  example:
    description: 수행하는 작업 설명
    keywords: [검색어, command phrase]
    command: C:\absolute\path\to\server.exe
    args: []
    cwd: C:\absolute\working\directory
    env:
      NON_SECRET_SETTING: value
    inherit_env:
      - SECRET_ENV_NAME
    load_timeout_seconds: 30
    call_timeout_seconds: 300

command와 cwd는 반드시 존재하는 절대 경로여야 합니다. 레지스트리 위치를 바꾸려면 라우터 프로세스에 MCP_ROUTER_REGISTRY를 설정합니다.

docs/, scripts/, examples/는 로컬 보조 자료로 기본 .gitignore 대상입니다.