使用说明

MCP网关

MCP网关是一个服务器聚合工具，它将多个模型上下文协议（MCP）服务器连接到一个网关中，通过统一的搜索、描述和调用接口从连接的服务器中公开所有工具，并且只公开5个工具。

上下文限制问题

当将客户端（Claude Code、Opencode等）连接到多个MCP服务器时，每个服务器都会列出其所有工具。10+MCP每个暴露10-50个工具，您可以在系统提示中轻松超过500+个工具描述：

10 servers × 20 tools each = 200+ tool descriptions
Each tool: 200-500 chars → 40KB-100KB of description just for tool schemas!

这产生了两个问题：

上下文溢出：许多LLM在任何对话发生之前就达到了上下文限制
认知超载：LLM很难从数百个选项中选择合适的工具

网关解决方案

MCP网关通过提供 工具搜索 而不是转储所有工具模式：

┌─────────────┐    gateway.search    ┌─────────────────┐    kubernetes::pods_list    ┌──────────────────┐
│  AI Client  │ ───────────────────► │   MCP Gateway   │ ─────────────────────────►  │  Kubernetes MCP  │
│             │                      │                 │                             │                  │
│             │ ◄────────────────────│                 │ ◄─────────────────────────  │                  │
└─────────────┘   pods_list schema   └─────────────────┘         pods output         └──────────────────┘

运作原理

MCP网关同时作为MCP客户端（连接到上游服务器）和MCP服务器（向下游客户端公开工具）运行：

┌──────────────┐      MCP       ┌─────────────────┐      MCP       ┌──────────────────┐
│  AI Client   │ ◄────────────  │   MCP Gateway   │ ◄────────────  │  Upstream Server │
│ (Claude, etc)│                │  (this gateway) │                │  (playwright,    │
└──────────────┘                └─────────────────┘                │   kubernetes...) │
                                                                   └──────────────────┘

网关启动并读取配置
对于每个配置的上游服务器，网关通过stdio（本地）或HTTP/WebSocket（远程）连接
Gateway从每台服务器获取工具目录
所有工具都被编入具有搜索功能的统一目录中
AI客户端连接到Gateway并使用 gateway.search 查找相关工具
仅调用客户端实际需要的工具

您会注意到使用的初始令牌减少了约40%。

安装

克劳德代码

添加到您的Claude MCP配置中：

{
  "mcpServers": {
    "gateway": {
      "command": "bunx",
      "args": ["@eznix/mcp-gateway@latest"]
    }
  }
}

OpenCode

添加到您的OpenCode MCP配置中：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-gateway": {
      "type": "local",
      "command": ["bunx", "@eznix/mcp-gateway@latest"]
    },
  }
}

您可以附加您的全局AGENTS.md(~/.config/opencode/AGENTS.md)用这个模板.

现在，您可以简单地枚举可用的MCP。

配置

MCP网关从JSON文件读取配置。默认情况下，它会查找：

作为第一个命令行参数提供的路径
MCP_GATEWAY_CONFIG 环境变量
~/.config/mcp-gateway/config.json

配置格式

{
  "local-server": {
    "type": "local",
    "command": ["bun", "run", "/path/to/server.ts"],
  },
  "remote-server": {
    "type": "remote",
    "url": "https://mcp.example.com",
    "enabled": true
  },
  "websocket-server": {
    "type": "remote",
    "url": "wss://mcp.example.com/ws",
    "enabled": true
  }
}

每个条目都指定：

type: "local" 或 "remote"
command （仅限本地）：带有命令和参数的数组，用于生成上游服务器
url （仅限远程）：远程MCP服务器的完整URL
transport （可选，仅远程）：覆盖传输检测("streamable_http" 或 "websocket").通常通过URL协议自动检测。
environment （仅限本地）：传递给生成进程的环境变量 {env:VAR_NAME} 替代支持
enabled：设置为false可跳过连接到此服务器

具有替换的环境变量

本地MCP服务器支持使用环境变量替换 {env:VAR_NAME} 语法：

{
  "jupyter-lab": {
    "type": "local",
    "command": ["uvx", "jupyter-mcp-server@latest"],
    "environment": {
      "JUPYTER_URL": "http://localhost:{env:JUPYTER_PORT}/",
      "JUPYTER_TOKEN": "{env:JUPYTER_TOKEN}",
      "DEBUG": "true"
    }
  }
}

这 {env:VAR_NAME} 占位符从当前流程环境中解析出来。如果未设置环境变量，则将其替换为空字符串。

码头工人

在Docker中使用HTTP传输运行MCP网关：

# Build the image
docker build -t mcp-gateway .

# Run with config mounted
docker run -p 3000:3000 \
  -v ./examples/config.json:/home/gateway/.config/mcp-gateway/config.json:ro \
  mcp-gateway

终点：

端点	描述
`GET /`	网关信息和端点
`GET /health`	健康检查
`/mcp`	MCP协议端点

例子：

curl http://localhost:3000/
# {"name":"MCP Gateway",...,"endpoints":{"mcp":"/mcp","health":"/health"}}

curl http://localhost:3000/health
# {"status":"ok"}

远程服务器配置

根据URL协议自动检测远程服务器：

http:// 或 https:// → 流式HTTP（推荐）
ws:// 或 wss:// →websocket

{
  "gh-grep": {
    "type": "remote",
    "url": "https://mcp.grep.app"
  },
  "custom-websocket": {
    "type": "remote",
    "url": "wss://my-server.com/mcp"
  }
}

可用工具

`gateway.search`

在所有连接的服务器上搜索工具。

{
  query: "kubernetes pods",
  limit: 10,  // optional, max 50
  filters: {
    server: "kubernetes",  // optional, filter by server name
  }
}

返回具有相关性得分的匹配工具。名称匹配的工具得到了增强。

`gateway.describe`

获取特定工具的详细信息。

{
  id: "kubernetes::pods_list"  // format: serverKey::toolName
}

返回包括inputSchema在内的完整工具架构。

`gateway.invoke`

同步执行工具并立即获得结果。

{
  id: "kubernetes::pods_list",
  args: { namespace: "default" },
  timeoutMs: 30000  // optional, default 30 seconds
}

`gateway.invoke_async`

启动异步工具执行。返回用于轮询的作业ID。

{
  id: "some-server::long-running-tool",
  args: { ... },
  priority: 10,  // optional, higher values run first
  timeoutMs: 60000
}

`gateway.invoke_status`

检查异步作业的状态。

{
  jobId: "job_123456789_abc123"
}

工具ID格式

所有网关工具都使用该格式 serverKey::toolName 识别工具：

kubernetes::pods_list
playwright::browser_navigate
github::create_issue

这 serverKey 是配置文件中的键名。

建筑

组件

MCPGateway类：主编排器
上游连接管理器：管理与MCP服务器的连接（stdio用于本地，HTTP/WebSocket用于远程）
刀具目录：包含元数据的所有可用工具的内存索引
作业队列：处理具有优先级顺序和并发限制的异步工具调用（默认情况下最多3个并发）
搜索引擎：具有BM25评分和模糊匹配的MiniSearch

搜索算法

搜索使用迷你搜索 BM25排名：

BM25评分：相关性算法
现场增压：姓名匹配（3x）、头衔匹配（2x）、描述/服务器匹配（1x）
模糊匹配：处理阈值为0.2的拼写错误（例如“kubenetes”→ 查找“kubernetes”）
前缀搜索：部分单词匹配（例如，“pod”匹配“pods_list”）

贡献

git clone https://github.com/eznix86/mcp-gateway.git
cd mcp-gateway
bun install

# Run locally (stdio transport)
bun run index.ts

# Run with Docker (HTTP transport on port 3000)
bun run docker:build && bun run docker:run

许可证

MIT许可证。请参阅许可证.

使用说明

MCP网关

上下文限制问题

网关解决方案

运作原理

安装

克劳德代码

OpenCode

配置

配置格式

具有替换的环境变量

码头工人

远程服务器配置

可用工具

gateway.search

gateway.describe

gateway.invoke

gateway.invoke_async

gateway.invoke_status

工具ID格式

建筑

组件

搜索算法

贡献

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器

`gateway.search`

`gateway.describe`

`gateway.invoke`

`gateway.invoke_async`

`gateway.invoke_status`