MCP Estuary

mcp河口

mcp-estuary 是一个最小的MCP网关，它将多个基于stdio的MCP服务器暴露为一个可流式传输的HTTP /mcp 终点。

日语自述： README-JP.md

计划任务管理软件

写 mcpe.json 形状与 mcp.json.

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": ".memory/memory.json"
      }
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "${TAVILY_API_KEY}"
      }
    }
  }
}

启动网关。

mcpe serve --config mcpe.json --listen 127.0.0.1:8080

将您的客户指向 mcp-estuary.

{
  "mcpServers": {
    "estuary": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8080/mcp"
      ]
    }
  }
}

只是使用。

克劳德示例：

{
  "mcpServers": {
    "estuary": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8080/mcp"
      ]
    }
  }
}

法典 config.toml 例子：

[mcp_servers.estuary]
url = "http://127.0.0.1:8080/mcp"

您还可以从CLI添加它：

codex mcp add estuary --url http://127.0.0.1:8080/mcp

特征矩阵

需求

• 转到1.26+
• 服务器使用的一个或多个运行时依赖项：

- uv - node / npm - docker

配置详情

mcpe.json 默认情况下从当前目录加载。

环境处理：

• ${VAR} 内部引用 env 首先从过程环境变量扩展，然后从 .env 旁边 mcpe.json.
• 未定义 ${VAR} 引用使该服务器无效。其他有效服务器仍在加载。
• _PATH 值在展开后相对于包含以下内容的目录进行解析 mcpe.json.
• MCPE_HOME 也读自相同 .env 当进程环境中尚未设置文件时。
• 基于Docker的MCP服务器不会自动接收主机环境变量。明确地传递它们 docker run args或容器配置。

配置修复：

• mcpe.json 带有尾随逗号的错误会自动修复。
• 修复后的差异将写入网关日志。

热重新加载：

• mcpe serve 民意调查 mcpe.json 并自动重新加载。
• 无效更改被隔离。健康的服务器继续提供服务。

服务器生命周期：

• 上游MCP服务器不会仅仅因为网关启动而保持驻留状态。
• tools/list 可以短暂启动上游服务器以发现工具元数据，然后立即停止。
• tools/call 仅启动目标上游服务器，并仅在空闲超时到期之前保持其活动状态。

命令

mcpe serve [--config PATH] [--use NAME ...] [--install-concurrency N] [--listen ADDR] [--foreground]
mcpe stop [--config PATH]
mcpe logs [--server NAME] [--follow]
mcpe doctor [--config PATH] [--use NAME ...]
mcpe status [--config PATH]
mcpe cache clean
mcpe config set --install-concurrency N
mcpe config set --systemd enable|disable [--config PATH] [--listen ADDR]
mcpe --help

安装并发优先级：

1. INSTALL_CONCURRENCY
2. serve --install-concurrency
3. mcpe config set --install-concurrency
4. 默认 2

状态目录

运行时状态存储在 ~/.mcp-estuary 默认情况下。

• 网关日志： ~/.mcp-estuary/logs/gateway.log
• 服务器日志： ~/.mcp-estuary/logs/servers/.log
• 托管工作目录： ~/.mcp-estuary/mcp-servers/
• 运行时状态： ~/.mcp-estuary/run/runtime-status.json

当 mcpe serve 开始，它也创造 mcp-servers-logs 旁边 mcpe.json 作为服务器日志目录的符号链接。

mcpe status 还显示是否 mcpe.service 已在用户systemd中注册、启用并处于活动状态。

HTTP端点

• POST /mcp
• GET /mcp
• DELETE /mcp
• GET /healthz

使用精确 /mcp MCP客户端的路径。指向客户 http://127.0.0.1:8080 或 http://127.0.0.1:8080/mcp/ 回报 404 page not found.

POST /mcp 支持：

• initialize
• notifications/initialized
• ping
• tools/list
• tools/call

暴露的工具名称被重写为 __.

码头工人

构建：

docker build -t mcp-estuary .

运行：

docker run --rm -p 8080:8080 \
  -v "$(pwd)/mcpe.json:/workspace/mcpe.json:ro" \
  -v "$(pwd)/.memory:/workspace/.memory" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v mcp-estuary-data:/root/.mcp-estuary \
  mcp-estuary

/var/run/docker.sock 仅当网关必须启动基于Docker的MCP服务器时才需要。

Docker Compose

compose.yaml 包括：

• 公布港口 8080
• mcpe.json 安装
• .memory 绑定挂载
• 持久容量 /root/.mcp-estuary
• /var/run/docker.sock 基于Docker的MCP服务器的挂载

开始：

docker compose up --build

示例

最小Docker MCP示例：

{
  "mcpServers": {
    "hello-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcpe-hello-docker-mcp"]
    }
  }
}

许可证

麻省理工学院