AI导哈

多用户MCP代理服务

MCP-Funnel是一个多用户MCP代理，将多个后端MCP服务器汇聚为每个用户的单一端点，提供懒加载、基于搜索的工具发现机制，适用于AI代码生成和多工具管理场景。

  • by Brusdeylins
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Brusdeylins/mcp-funnel

使用说明

MCP漏斗

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

建筑

graph LR
    C1[MCP Client<br>Claude Code] -->|Streamable HTTP<br>+ Bearer Token| F[MCP-Funnel]
    C2[MCP Client<br>Cursor] -->|Streamable HTTP<br>+ 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漏斗公开了所需的发现端点：

端点 描述
/.well-known/oauth-protected-resource 受保护的资源元数据（RFC 9728）
/.well-known/oauth-authorization-server 授权服务器元数据（RFC 8414）
/oauth/register 动态客户端注册（RFC 7591）
/oauth/authorize 授权端点
/oauth/token 令牌端点

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

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

模式 API密钥 OAuth JWT
both （默认） 是 是
oauth 否 是
legacy 是 否

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

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

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

后端身份验证

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

方法 说明
无 无身份验证
承载令牌 静态 Authorization: Bearer <token> 头球
基本身份验证 Authorization: Basic <base64> 头球
API密钥 自定义头（例如。， X-API-Key)
URL参数 附加到URL的令牌
自定义标头 任意标头名称和值
OAuth 2.1 具有自动令牌刷新功能的完整OAuth客户端

后端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. 每次重新连接之前，令牌都会被持久化并自动刷新

配置

核心

设置 环境变量 默认值 描述
港口 PORT 3000 HTTP服务器端口
数据目录 DATA_DIR ./data 持久数据存储
单用户模式 SINGLE_USER false 无需身份验证即可运行
日志级别 LOG_LEVEL info Winston日志级别

会话

设置 环境变量 默认值 描述
会话秘密 SESSION_SECRET （自动生成） 会话cookie机密
会话最大年龄 SESSION_MAX_AGE 2592000000 （30d） 会话TTL（毫秒）

管理员引导

设置 环境变量 默认值 描述
管理员用户 ADMIN_USER （无） 首次启动时自动创建管理员
管理员通行证 ADMIN_PASS （无） 管理员密码（最少8个字符）

OAuth 2.1

设置 环境变量 默认值 描述
身份验证模式 AUTH_MODE both both, oauth，或 legacy
发卡机构URL OAUTH_ISSUER （汽车从 BASE_URL) 智威汤逊发行人索赔
令牌寿命 OAUTH_TOKEN_LIFETIME 3600 访问令牌TTL（秒）
刷新寿命 OAUTH_REFRESH_TOKEN_LIFETIME 86400 刷新令牌TTL（秒）
基本URL BASE_URL http://localhost:{PORT} OAuth元数据的公共URL

协议

设置 环境变量 默认值 描述
允许的来源 ALLOWED_ORIGINS （无） 允许以逗号分隔的来源
协议版本 MCP_PROTOCOL_VERSIONS 2025-11-25,2025-03-26 已接受的MCP版本

命令行界面

Usage: mcp-funnel [options]

Options:
  -p, --port <number>    HTTP port (default: 3000)
  -d, --data-dir <path>  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

相关 MCP