MCP漏斗
多用户MCP代理,将多个后端MCP服务器汇集到每个用户的单个端点。MCP漏斗没有直接公开数百个工具,而是提供了3个元工具,用于基于搜索的懒惰工具发现,从而将LLM上下文的使用率降至最低。100%AI生成代码(使用Claude code进行代理编码)。
建筑```mermaid
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(推荐)```bash
docker compose up --build
打开 http://localhost:3000,完成管理员设置,然后通过仪表板添加MCP服务器。
通过环境自动创建管理员```bash
ADMIN_USER=admin ADMIN_PASS=your-password docker compose up --build
### 本地(npm)```bash
npm install
npm run build
npm start -- --port 8080 --data-dir ./my-data
MCP客户端配置
API密钥(默认)```json
{
"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"]`
1. 请求令牌: `POST /oauth/token` 随着 `grant_type=client_credentials&client_id=...&client_secret=...`
1. 使用令牌: `Authorization: Bearer `
## 后端身份验证
添加后端MCP服务器时,MCP漏斗支持多种身份验证方法:
|方法|说明|
|---|---|
|无|无身份验证|
|承载令牌|静态 `Authorization: Bearer ` 头球
|基本身份验证| `Authorization: Basic ` 头球
|API密钥|自定义头(例如。, `X-API-Key`) |
|URL参数|附加到URL的令牌|
|自定义标头|任意标头名称和值|
| **OAuth 2.1** |具有自动令牌刷新功能的完整OAuth客户端|
### 后端OAuth 2.1
对于需要OAuth 2.1的后端,MCP漏斗充当OAuth客户端:```mermaid
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
- 打开web仪表板中的MCP服务器页面
- 单击服务器条目上的OAuth按钮
- 输入后端的基本URL——MCP漏斗会自动发现OAuth元数据
- 如果动态客户端注册可用,则客户端会自动注册,否则手动输入凭据
- 点击“授权”完成登录流程
- 每次重新连接之前,令牌都会被持久化并自动刷新
配置
核心
| 设置 | 环境变量 | 默认值 | 描述 |
|---|---|---|---|
| 港口 | 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 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
发展```bash
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
