MCP Funnel

MCP漏斗

多用户MCP代理，将多个后端MCP服务器汇集到每个用户的单个端点。MCP漏斗没有直接公开数百个工具，而是提供了3个元工具，用于基于搜索的懒惰工具发现，从而将LLM上下文的使用率降至最低。100%AI生成代码（使用Claude code进行代理编码）。

建筑

graph LR
    C1[MCP Client
Claude Code] -->|Streamable HTTP
+ Bearer Token| F[MCP-Funnel]
    C2[MCP Client
Cursor] -->|Streamable HTTP
+ OAuth JWT| F

    F -->|HTTP| B1[Backend MCP Server 1]
    F -->|SSE| B2[Backend MCP Server 2]
    F -->|Stdio| B3[Backend MCP Server 3]
    F -->|HTTP + OAuth| B4[Backend MCP Server 4]

    style F fill:#4a90d9,color:#fff

它是如何工作的：

• 客户端通过单个端点连接到MCP漏斗(/mcp)
• 每个用户都有自己的一组后端MCP服务器，通过web仪表板进行配置
• 通过懒惰的方式发现工具 mcp_discover_tools （搜索）→ mcp_get_tool_schema （检查）→ mcp_call_tool （执行）
• 所有MCP规范功能（资源、提示、通知、采样、启发）都是透明代理的

特性

MCP代理

• 3个用于懒惰发现的元工具： mcp_discover_tools, mcp_get_tool_schema, mcp_call_tool
• 模糊匹配与相关性评分（Levenshtein距离）——拼写错误仍然可以找到工具
• 支持流式HTTP、SSE和Stdio传输到后端
• 每个服务器工具启用/禁用控制
• 指数回退自动重新连接

MCP规范2025-11-25

• 完全代理透明--保留工具/资源/提示元数据（标题、图标、注释、outputSchema）
• 能力协商（抽样、启发、根）
• 双向通知转发（进度、取消、列表更改）
• 采样和启发传递（后端到客户端）
• 资源模板、分页、补全
• 实验任务支持

认证

• 入站 （客户端到漏斗）：传统API密钥、OAuth 2.1（授权代码+PKCE、客户端凭据）或两者都有
• 出站 （漏斗到后端）：静态令牌，基本Auth，API密钥，OAuth 2.1自动刷新令牌
• 用户API密钥隔离
• MCP协议版本验证、源验证、WWW身份验证标头

行政

• 带有MCP服务器管理、工具控制和用户管理的Web仪表板
• 单用户模式(--single-user)用于本地使用，无需身份验证
• 基于文件的存储（不需要数据库）
• Docker支持

快速开始

Docker（推荐）

docker compose up --build

打开 http://localhost:3000，完成管理员设置，然后通过仪表板添加MCP服务器。

通过环境自动创建管理员

ADMIN_USER=admin ADMIN_PASS=your-password docker compose up --build

本地（npm）

npm install
npm run build
npm start -- --port 8080 --data-dir ./my-data

MCP客户端配置

API密钥（默认）

{
  "mcpServers": {
    "mcp-funnel": {
      "type": "streamable-http",
      "url": "https://your-host/mcp",
      "headers": {
        "Authorization": "Bearer mcp_your-api-key-here"
      }
    }
  }
}

API键显示在web面板的“设置”下。

OAuth 2.1

支持OAuth 2.1的MCP客户端可以通过标准流程进行身份验证。MCP漏斗公开了所需的发现端点：

支持的资助类型： authorization_code （用PKCE S256）， refresh_token, client_credentials

AUTH_MODE 控制接受哪些身份验证方法：

客户端凭据（机器到机器）

对于没有用户上下文的自动化系统：

1. 注册客户： POST /oauth/register 随着 grant_types: ["client_credentials"]
2. 请求令牌： POST /oauth/token 随着 grant_type=client_credentials&client_id=...&client_secret=...
3. 使用令牌： Authorization: Bearer

后端身份验证

添加后端MCP服务器时，MCP漏斗支持多种身份验证方法：

后端OAuth 2.1

对于需要OAuth 2.1的后端，MCP漏斗充当OAuth客户端：

sequenceDiagram
    participant U as Admin (Browser)
    participant F as MCP-Funnel
    participant B as Backend IdP

    U->>F: Click OAuth button on server
    U->>F: Enter backend URL
    F->>B: GET /.well-known/oauth-authorization-server
    B-->>F: Metadata (endpoints, scopes)
    F->>B: POST /oauth/register (dynamic registration)
    B-->>F: client_id, client_secret
    U->>F: Click "Authorize"
    F-->>U: Redirect to backend login
    U->>B: Login + consent
    B-->>F: Authorization code (callback)
    F->>B: POST /oauth/token (code + PKCE)
    B-->>F: access_token, refresh_token
    Note over F: Token persisted, auto-refreshed

1. 打开web仪表板中的MCP服务器页面
2. 单击服务器条目上的OAuth按钮
3. 输入后端的基本URL——MCP漏斗会自动发现OAuth元数据
4. 如果动态客户端注册可用，则客户端会自动注册，否则手动输入凭据
5. 点击“授权”完成登录流程
6. 每次重新连接之前，令牌都会被持久化并自动刷新

配置

核心

会话

管理员引导

OAuth 2.1

协议

命令行界面

Usage: mcp-funnel [options]

Options:
  -p, --port     HTTP port (default: 3000)
  -d, --data-dir 
  Data directory (default: ./data)
  --single-user          Run in single-user mode (no auth)
  -h, --help             Show help
  -V, --version          Show version

数据存储

所有数据都以JSON文件存储在配置的数据目录中：

{dataDir}/
  auth.json                  Admin credentials, user accounts, API keys
  session-secret.txt         Auto-generated session secret
  stats.json                 Per-user request statistics
  sessions/                  File-based session store
  servers/{userId}.json      Per-user MCP server configurations
  oauth/
    clients.json             Registered OAuth clients
    jwk-private.json         RSA key pair for JWT signing

发展

npm install
npm run dev      # Watch mode with auto-rebuild
npm run lint     # ESLint check
npm run lint:fix # ESLint auto-fix
npm test         # Run tests (140 tests)

许可证

仅限GPL-3.0