MCP 게이트웨이

Claude와 MCP 서버 사이에 위치하는 지연 로딩 프록시입니다. 시작 시 모든 서버를 로드하는 대신(수백 개의 도구 스키마가 컨텍스트에 덤프되어 토큰을 낭비함), 게이트웨이는 4개의 경량 도구만 노출합니다. 백엔드 서버는 실제로 필요할 때만 시작됩니다.

이전: 10개의 MCP 서버 = 모든 대화에 200개 이상의 도구 스키마가 로드됨 = 수천 개의 토큰 낭비.

이후: 게이트웨이 뒤에 10개의 MCP 서버 = 4개의 도구 스키마만 로드됨. 각 서버는 필요할 때 시작됨.

문제점

Claude Code에 추가하는 모든 MCP 서버는 모든 도구를 미리 등록합니다. 일반적인 서버는 10~~30개의 도구를 가지며, 각 도구는 전체 JSON 스키마를 포함합니다. 10개의 서버가 있으면 질문을 하기도 전에 100~~300개의 도구 정의가 컨텍스트 창을 차지합니다.

대부분의 대화는 1~2개의 서버만 사용합니다. 나머지는 불필요한 짐일 뿐입니다.

작동 방식

게이트웨이는 Claude에 4개의 도구를 노출합니다:

도구	기능
`gateway_list_servers`	사용 가능한 서버와 상태를 표시
`gateway_load_server`	서버에 연결하고 도구를 검색
`gateway_call_tool`	연결된 서버의 도구를 호출
`gateway_reload_server`	서버를 재연결 (코드 변경 사항 반영)

Claude가 서버를 필요로 하면 gateway_load_server를 호출합니다. 게이트웨이는 하위 프로세스를 시작하고, MCP 핸드셰이크를 수행하며, 연결을 캐시합니다. 이후 호출은 실행 중인 프로세스를 재사용합니다.

사용되지 않는 서버는 절대 시작되지 않습니다. 토큰 낭비가 없습니다.

빠른 시작

git clone https://github.com/raiansar/mcp-gateway.git
cd mcp-gateway
./install.sh

config.json을 편집하여 서버를 추가한 다음, Claude Code에 게이트웨이를 추가하세요:

claude mcp add gateway -- /path/to/mcp-gateway/run.sh

이것으로 끝입니다. 이제 모든 서버가 단일 게이트웨이 뒤에 위치하게 됩니다.

구성

config.json은 서버 이름과 연결 세부 정보를 매핑한 간단한 파일입니다. 게이트웨이는 stdio(로컬 프로세스) 및 HTTP(원격 서버) 전송 방식을 모두 지원합니다.

Stdio 서버 (로컬)

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "some-mcp-server@latest"],
      "env": {
        "API_KEY": "your-key"
      },
      "timeout": 30,
      "description": "What this server does"
    }
  }
}

HTTP 서버 (원격)

{
  "servers": {
    "remote-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      },
      "timeout": 60,
      "description": "Remote MCP server"
    }
  }
}

Python 서버 (uv)

{
  "servers": {
    "my-python-server": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/server", "server-name"],
      "env": {},
      "timeout": 120,
      "description": "Python server managed by uv"
    }
  }
}

구성 필드

필드	필수	기본값	설명
`type`	아니요	`stdio`	전송 방식: `stdio`, `http`, `sse`, 또는 `streamable-http`
`command`	예 (stdio)	-	서버를 실행할 명령어
`args`	아니요	`[]`	명령어 인수
`env`	아니요	`{}`	환경 변수
`url`	예 (http)	-	서버 URL
`headers`	아니요	`{}`	HTTP 헤더 (인증 토큰 등)
`timeout`	아니요	30/60	요청 시간 제한(초) (stdio는 30, http는 60)
`description`	아니요	-	`gateway_list_servers`에 표시되는 사람이 읽을 수 있는 설명

기존 MCP 서버 마이그레이션

이미 Claude Code에 MCP 서버가 구성되어 있다면, 게이트웨이로 옮기세요:

이전 (~/.claude.json 또는 Claude Desktop 구성):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": { "TAVILY_API_KEY": "tvly-xxx" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {}
    }
  }
}

이후 (config.json):

{
  "servers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" },
      "description": "GitHub - repos, issues, PRs, code search"
    },
    "tavily": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": { "TAVILY_API_KEY": "tvly-xxx" },
      "description": "Tavily AI search"
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {},
      "description": "File system access"
    }
  }
}

그런 다음 Claude에서 개별 서버를 제거하고 게이트웨이만 추가하세요:

claude mcp remove github -s user
claude mcp remove tavily -s user
claude mcp remove filesystem -s user
claude mcp add gateway -- /path/to/mcp-gateway/run.sh

사용법

구성이 완료되면 Claude는 자동으로 게이트웨이를 사용합니다. 일반적인 상호작용:

Claude가 gateway_list_servers를 호출하여 사용 가능한 서버를 확인합니다.
Claude가 GitHub가 필요할 때 gateway_load_server("github")를 호출합니다.
Claude가 도구를 사용하기 위해 gateway_call_tool("github", "search_repositories", '{"query": "mcp"}')를 호출합니다.
GitHub 서버는 동일한 세션 내의 후속 호출을 위해 계속 실행 상태를 유지합니다.

구성의 description 필드는 Claude가 특정 작업에 어떤 서버를 로드할지 결정하는 데 도움을 주므로, 설명을 잘 작성하세요.

RTK와의 차이점

RTK는 셸 명령 출력(git, ls, 테스트 러너 등)을 압축하여 토큰 소비를 60~90% 줄여주는 CLI 프록시입니다.

MCP 게이트웨이는 다른 문제를 해결합니다. 모든 도구를 미리 등록하는 대신 필요할 때 서버를 지연 로딩하여 MCP 도구 스키마 비대화를 방지합니다.

	MCP 게이트웨이	RTK
문제	유휴 MCP 서버의 도구 스키마가 컨텍스트를 낭비함	장황한 CLI 출력이 컨텍스트를 낭비함
방법	서버 지연 로딩, 4개의 프록시 도구 노출	컨텍스트에 도달하기 전에 명령 출력 압축
시기	시작 / 도구 등록	런타임 / 명령 실행
범위	MCP 서버 관리	셸 명령 (git, npm, cargo 등)

두 도구는 상호 보완적입니다. 최대의 토큰 절약을 위해 둘 다 사용하세요.

요구 사항

Python 3.10+
mcp 패키지 (install.sh로 설치됨)

라이선스

MIT

MCP Gateway