使用说明

MCP 锥形管（或 MCP 漏斗）

一个模型上下文协议（MCP）代理服务器，它将多个MCP服务器聚合到一个单一接口中，使您能够通过Claude Desktop或Claude Code CLI同时使用来自多个来源的工具。

🎯 目的

大多数MCP服务器会公开所有工具，且不提供过滤选项，从而浪费了宝贵的上下文空间

MCP漏斗使您能够：

同时连接到多个MCP服务器（GitHub、Memory、Filesystem等）
细粒度工具过滤隐藏您不需要的特定工具
基于模式的过滤使用通配符来隐藏整个类别的工具
减少上下文使用通过仅暴露必要工具，显著减少令牌消耗

🏗️ 建筑学

┌────────────────────────┐
│ CLI (e.g. Claude Code) │
└──────┬─────────────────┘
       │ MCP Protocol via stdio
┌──────▼──────┐
│  MCP Funnel │ ← Filtering and dynamic discovery happens here
└──────┬──────┘
       │
   ┌───┴──────┬─────────┬─────────┐
   │          │         │         │
┌──▼────┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│GitHub │ │Memory │ │FS     │ │ ...   │ ← Each exposes all tools
└───────┘ └───────┘ └───────┘ └───────┘

MCP漏斗：

作为客户端连接到多个MCP服务器
从每台服务器接收所有工具
应用您的过滤规则
仅向客户端暴露过滤后的工具
将工具调用路由到相应的后端服务器

🚀 功能

多服务器聚合连接到任意数量的MCP服务器
工具命名空间自动前缀功能可避免命名冲突（github__create_issue， memory__store_memory)
灵活过滤使用通配符模式显示/隐藏工具
精细控制过滤掉服务器不允许你禁用的单个工具
上下文优化通过选择性过滤，将MCP工具上下文使用量减少40-60%
定制运输服务支持基于stdio的MCP服务器（Docker、NPX、本地二进制文件）
服务器日志前缀添加明确标识出哪台服务器记录了什么日志
动态工具发现减少初始上下文使用量的实验性功能（参见限制）
核心工具模式超极简上下文模式，仅展示选定的MCP漏斗工具，并提供动态桥接功能（上下文缩减95%以上）

💡 为什么使用MCP漏斗？

上下文问题

一个典型的MCP（多通道板）设置可能会暴露：

GitHub MCP：约70个工具
内存MCP：约30种工具
文件系统MCP：约15个工具
总计：115+个工具，消耗40,000个标记

这些工具中的许多很少被使用：

工作流管理工具
团队/组织工具
调试和诊断工具
仪表盘界面
高级嵌入操作

或者用聊天来“交谈”：

之前

For this `.mcp.json` config

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "/Users/me/_mcp/mcp-memory-service", "run", "memory", "server"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "API_KEY"]
    },
    "code-reasoning": {
      "command": "npx",
      "args": ["-y", "@mettamatt/code-reasoning"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "allowed/file/path"
      ]
    },
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/github/github-mcp-server"
      ],
      "secretProviders": [
        { "type": "dotenv", "config": { "path": ".env" } }
      ]
    }
  }
}
```

> /context
  ⎿  ⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   Context Usage
     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-opus-4-1-20250805 • 42k/200k tokens (21%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ MCP tools: 25.4k tokens (12.7%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 96 tokens (0.0%)

之后

> /context
⎿  ⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀   Context Usage
⛀ ⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   claude-opus-4-1-20250805 • 18k/200k tokens (9%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ MCP tools: 2.4k tokens (1.2%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 96 tokens (0.0%)

然后使用它：

> discover tool for code reasoning

⏺ I'll help you discover the code reasoning tool.

⏺ mcp-funnel - discover_tools_by_words (MCP)(words: "reasoning", enable: false)
  ⎿  Found 1 tools:
     ○ code-reasoning__code-reasoning: 🧠 A detailed tool for dynamic and reflective problem-solving through sequential thinking.
     … +29 lines (ctrl+o to expand)

⏺ Found it! The code-reasoning__code-reasoning tool is available for detailed code analysis and reasoning. Let me enable it:

⏺ mcp-funnel - load_toolset (MCP)(tools: ["code-reasoning__code-reasoning"])
  ⎿  Loaded 1 tools matching specified patterns
⏺ The code reasoning tool is now enabled. It provides:
  - Dynamic problem-solving through sequential thinking
  - Ability to branch and explore alternatives
  - Revision capabilities to correct earlier thinking
  - Flexible thought progression that adapts as understanding deepens

  You can now use this tool for analyzing code logic, understanding complex implementations, and working through programming challenges step-by-step.

🔧 安装

安装自定义命令

MCP Funnel 支持动态安装来自 npm 包的额外命令。您可以将这些命令全局安装到您的用户目录（~/.mcp-funnel/packages）中，这样它们就可以在您的所有项目中使用。

使用 `manage_commands` 工具

manage_commands 这是一个内置的MCP漏斗工具，用于安装、更新和移除命令包，且无需单独的CLI封装。只要（满足条件），该工具默认即可使用 exposeCoreTools 未设置（或明确包含 manage_commands）。

示例安装请求通过 bridge_tool_request （克劳德、Codex CLI 等）：

{
  "name": "manage_commands",
  "arguments": {
    "action": "install",
    "package": "@awesome-org/mcp-command",
    "version": "1.2.3"
  }
}

支持的有效载荷字段：

action： install， update，或者 uninstall （必需）。
packagenpm 包规范或之前安装的命令名称（必填）。
version可选版本（仅安装）——例如。， "1.2.3".
force布尔标志，用于指示即使已存在也重新安装（仅安装）。
removeData布尔标志，用于删除缓存数据（仅在卸载时）。

响应包括有关命令的结构化详细信息、发现的任何工具，以及热重载是否成功。当在MCP客户端内运行时，您可以直接调用工具；无需额外的CLI（命令行界面）配置。

命令发现

用户安装的命令会自动被发现 ~/.mcp-funnel/packages/node_modules/ 并且与内置命令一同加载。它们尊重您的配置：

如果 commands.list 如果指定了（此设置），则仅加载白名单中的命令
命令可以通过 hideTools 模式；图案
命令中的工具通过以下方式过滤： exposeTools 模式；图案；样式

⚙️ 配置

MCP漏斗支持两种指定配置的方式：

隐含的 (默认): 寻找 .mcp-funnel.json 在当前工作目录中
```
npx mcp-funnel  # Uses ./.mcp-funnel.json
```
明确的；直白的指定自定义配置文件路径
```
npx mcp-funnel /path/to/config.json
```
用户基础配置（自动合并）

如果存在， ~/.mcp-funnel/.mcp-funnel.json 与项目配置合并。项目值覆盖用户基本值。数组被替换（不进行拼接）。

创建一个 .mcp-funnel.json 在您的项目目录中找到文件：

{
  "servers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"],
      "secretProviders": [{ "type": "dotenv", "config": { "path": ".env" } }]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  },
  "hideTools": [
    "github__list_workflow_runs",
    "github__get_workflow_run_logs",
    "memory__debug_*",
    "memory__dashboard_*",
    "github__get_team_members"
  ]
}

传递秘密/环境变量示例：GitHub MCP

以下是配置GitHub MCP并安全处理令牌的简单方法：

.mcp-funnel.json：

{
  "servers": {
    "github": {
      "transport": {
        "type": "streamable-http",
        "url": "https://api.githubcopilot.com/mcp/"
      },
      "auth": {
        "type": "bearer",
        "token": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      },
      "secretProviders": [
        { "type": "dotenv", "config": { "path": ".env" } }
      ]
    }
  }
}

.env:（通常指的是环境配置文件）

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_github_token_here

就是这些！那个 secretProviders 自动从（指定位置）加载您的令牌 .env，确保其安全，并将其放在配置文件之外。

配置选项

服务器MCP服务器连接记录（服务器名称作为键）
- 密钥：服务器名称（用作工具前缀）
- command执行命令
- args命令参数（可选）
- env环境变量（可选，已弃用 - 请改用 secretProviders）
- secretProviders用于安全管理环境变量的秘密提供程序配置数组（推荐）
默认密钥提供程序默认密钥提供程序应用于所有服务器（可选）
默认透传环境默认传递给所有服务器的环境变量（可选）
始终可见的工具始终暴露的工具模式，绕过发现模式（可选）
**暴露工具（或“揭露工具”）**包含用于暴露外部工具的模式（可选）
隐藏工具为外部工具排除隐藏模式（可选）
暴露核心工具包含内部MCP漏斗工具的模式（可选，默认启用所有）

“alwaysVisibleTools”与“exposeTools”

使用 暴露工具 当你希望某个工具在启动时可见时，无需单独列出。对于服务器支持的工具，无需在alwaysVisibleTools中重复添加。
使用 始终可见的工具 当你需要一个服务器工具来绕过所有门控（暴露/隐藏，以及未来的模式变化）时，它优于hideTools。你无需在exposeTools中重复设置。
命令命令工具通过其工具名称直接暴露（例如。， npm_lookup， ts-validate) 或使用通配符 (例如。， npm_*) 在 exposeTools/hideTools 模式中。

过滤模式

模式与带前缀的工具名称相匹配（serverName__toolName) 并支持通配符 (*)：

单个工具：

github__get_team_members - 从GitHub服务器中隐藏特定工具
memory__check_database_health - 从内存服务器中隐藏特定工具

通配符模式：

memory__dashboard_* - 来自内存服务器的所有仪表板工具
github__debug_* - 来自GitHub服务器的所有调试工具
*__workflow_* - 来自任何服务器的所有与工作流相关的工具
memory__ingest_* - 来自内存服务器的所有摄入工具
*__list_* - 来自任何服务器的所有列表工具

常见的过滤示例：

"hideTools": [
"memory__dashboard_*",         // Hide all dashboard tools from Memory
"memory__debug_*",            // Hide all debug tools from Memory
"memory__ingest_*",           // Hide ingestion tools from Memory
"github__get_team_members",   // Hide specific GitHub tool
"github__*_workflow_*",       // Hide workflow tools from GitHub
"*__list_*_artifacts"         // Hide artifact listing tools from all servers
]

注：始终使用服务器前缀（例如。， github__， memory__) 以针对特定服务器的工具。使用 *__ 起初是匹配来自任何服务器的工具。

核心工具过滤

MCP漏斗包含用于发现和连接的内部工具。通过（相关机制）控制哪些核心工具被暴露出来 exposeCoreTools：

"exposeCoreTools": ["discover_*", "load_toolset"]  // Only expose discovery tools and toolset loading

可用的核心工具：

discover_tools_by_words - 通过关键词搜索工具
get_tool_schema - 获取工具的输入模式
bridge_tool_request - 动态执行工具
load_toolset - 加载预定义的工具模式

如果 exposeCoreTools 未指定时，默认启用所有核心工具。

🚀 使用方法

使用 Claude Code 命令行界面 (CLI)

添加到您的配置中（例如。 path/to/your/project/.mcp.json)：

{
  "mcpServers": {
    "mcp-funnel": {
      "command": "npx",
      "args": ["-y", "mcp-funnel"]
    }
  }
}

这将使用 .mcp-funnel.json 从您当前的工作目录中。要使用自定义配置路径：

{
  "mcpServers": {
    "mcp-funnel": {
      "command": "npx",
      "args": ["-y", "mcp-funnel", "/path/to/your/.mcp-funnel.json"]
    }
  }
}

借助Google Gemini

添加到你的配置中（例如。 path/to/your/project/.gemini/settings.json):

{
  "mcpServers": {
    "mcp-funnel": {
      "command": "npx",
      "args": ["-y", "mcp-funnel"]
    }
  }
}

使用Codex CLI

添加到你的配置中（例如。 ~/.codex/config.toml)：

[mcp_servers.mcp-funnel]
command = "npx"
args = ["-y", "mcp-funnel"]

CLI 入门/上手指南

启动引导式迁移流程以巩固现有的CLI配置：

npx mcp-funnel init

这个命令：

扫描Claude Code/Gemini的典型配置文件.mcp.json， .gemini/settings.json), Claude Desktop（克劳德桌面版）~/.claude.json), 和《烹饪法典》(~/.codex/config.toml）。
列出它找到的每个MCP服务器，并允许您选择哪些服务器应该迁移到 .mcp-funnel.json。
将选定的服务器合并到 .mcp-funnel.json在需要时，使用推荐的默认值创建文件。
重写每个客户端配置，以便仅保留一个 mcp-funnel 条目仍然存在，指向合并后的配置。

每一次写入操作都会在明确的确认之后进行，因此您可以在更改实施之前对其进行审查。

示例提示

配置完成后，您可以使用自然语言与您的聚合工具进行交互：

"Load PRs for https://github.com/chris-schra/mcp-funnel"

这之所以能无缝工作，是因为MCP Funnel为您的GitHub服务器工具提供了适当的命名空间聚合！

🎮 工具可见性控制

MCP Funnel 提供了一个三级可见性系统，用于管理哪些工具被暴露出来：

1. 始终可见的工具（`alwaysVisibleTools`)

符合这些模式的工具是 从启动时就一直处于暴露状态即使使用动态发现模式（空白名单），也表现完美。非常适合您始终希望随时可用的关键工具。

{
  "alwaysVisibleTools": [
    "github__create_pull_request", // Always show this specific tool
    "memory__store_*" // Always show all store operations
  ]
}

2. 可发现的工具（`exposeTools`)

当使用一个空的允许列表时（exposeTools: []这些工具最初是隐藏的，但可以通过（某种方式）动态地发现并启用 load_toolset当被列入允许列表时 exposeTools从启动时起，它们就可见了。

3. 隐藏工具（`hideTools`）

无论其他设置如何，匹配这些模式的工具都不会被暴露出来。

动态发现

从一个最小化的表面开始，并按需启用工具：

{
  "exposeTools": [],
  "alwaysVisibleTools": [],
  "exposeCoreTools": [
    "discover_*",
    "get_tool_schema",
    "load_toolset",
    "bridge_tool_request"
  ]
}

运行时流程：

搜索： discover_tools_by_words 带有关键词（例如，“context7”）。
启用： load_toolset 带有明确的工具名称或模式（例如，["context7__resolve_library_id", "context7__get-library-docs"]）。
呼叫：正常使用已启用的工具。

🚀 核心工具模式（超低情境依赖）

核心工具模式允许您仅公开MCP漏斗的内部工具以进行动态发现。当您设置时 exposeCoreTools 为了达到一个最小集，MCP Funnel 可以仅暴露最少数量的（信息/选项/功能等） 3个工具 而不是100多个：

通过词语发现工具按关键词搜索工具
**获取工具模式（或工具模式定义）**获取任何工具的输入模式
桥接工具请求动态执行任何工具

它是如何运作的

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "secretProviders": [{ "type": "dotenv", "config": { "path": ".env" } }]
    }
  },
  "exposeCoreTools": [
    "discover_tools_by_words",
    "get_tool_schema",
    "bridge_tool_request"
  ]
}

使用示例

简单的流程：

User: "Load PRs for https://github.com/chris-schra/mcp-funnel"
Claude: *Automatically discovers GitHub tools, gets schema, and executes via bridge*

分步工作流程：

1. "Find tools for working with files"
   → Claude uses discover_tools_by_words
   → Returns: filesystem__read_file, filesystem__write_file, etc.

2. "Get the schema for filesystem__read_file"
   → Claude uses get_tool_schema
   → Returns: Input parameters and types

3. "Read the README.md file"
   → Claude uses bridge_tool_request
   → Executes: {"tool": "filesystem__read_file", "arguments": {"path": "README.md"}}

好处

全部功能所有工具均可继续使用
智能发现克劳德能够自然地找到并使用工具
今天的工作无需等待Claude Code更新

权衡取舍

较难发现（工具一开始不可见）
在发现/模式步骤上存在轻微的开销
最适合在您只使用不到10%可用工具的情况下使用

🔍 动态工具发现（实验性）

MCP漏斗包含一个 discover_tools_by_words 一个允许通过关键词搜索工具的工具。然而， 这个功能目前的实用性有限：

⚠️ 当前限制

Claude CLI 不支持动态工具更新一旦会话开始，工具列表即固定不变。这意味着：

该 discover_tools_by_words 工具可以找到匹配的工具
它可以在MCP漏斗（或MCP流程）的内部状态中“启用”它们
但克劳德只有在你重新启动会话后才能看到新启用的工具

我们热切期待这些问题得到解决：

claude-code#7519（这个翻译保持了原样的形式，因为“claude-code#7519”可能是一个特定的代码或标识符，直接翻译并无实际意义，所以这里仅做形式上的保留。） - 动态工具发现支持
claude-code#4118 - 运行时工具更新

一旦这些功能实现，动态发现将通过按需仅加载您所需的工具，从而显著减少初始上下文的使用。

🔒 安全考量

🔐 密钥管理

MCP Funnel 包含一个遵循最小特权原则的安全密钥管理系统。您无需将所有环境变量暴露给 MCP 服务器，而是可以使用 秘密供应商 精确控制每台服务器接收哪些秘密。

快速示例：

{
  "secretProviders": [
    { "type": "dotenv", "path": ".env" },      // Load from .env files
    { "type": "process", "prefix": "MCP_" },   // Filter env vars by prefix
    { "type": "inline", "values": { ... } }    // Define inline secrets
  ]
}

主要优势：

向子进程暴露的环境变量最小化
多种提供者类型（dotenv、process、inline）及优先级规则
内置安全过滤功能，防止凭证泄露
在所有MCP服务器上实现集中式的密钥管理

📖（书本的图标，无具体文字含义，可理解为“书”或“书籍”的象征） 查看完整的Secret Management指南 →

基础设施安全

文件系统访问小心文件系统服务器路径
Docker 权限如果使用容器化服务器，请确保Docker套接字访问正确无误
网络隔离考虑在隔离环境中运行敏感操作

🗺️ 路线图

[x] 用于增强服务器管理的连接重试逻辑
[ ] 健康监测与状态报告
[x] 服务器故障时的优雅降级
[ ] 具有可配置级别的结构化日志记录
[ ] 指标和性能监控
[ ] WebSocket传输支持
[ ] 完整的动态工具发现功能（受限于Claude Code CLI的支持）

🛠️ 开发

对于本地开发环境的搭建、调试和测试：

📖（书本的符号，通常表示书籍或阅读） 查看开发指南 →

🤝 贡献（或“参与贡献”）

欢迎投稿！需要重点关注的领域：

错误处理使MCP漏斗对服务器故障具有鲁棒性
测试为除Claude Code以外的其他客户端添加全面的测试覆盖率
记录日志实现结构化日志记录

📄 许可证

麻省理工学院（MIT）- 请参阅仓库根目录中的LICENSE文件