MCP Funnel

A Model Context Protocol (MCP) proxy server that aggregates multiple MCP servers into a single interface, enabling you to use tools from multiple sources simultaneously through Claude Desktop or Claude Code CLI.

🎯 Purpose

Most MCP servers expose all their tools with no filtering options, consuming valuable context space

MCP Funnel enables you to:

Connect to multiple MCP servers simultaneously (GitHub, Memory, Filesystem, etc.)
Fine-grained tool filtering: Hide specific tools that you don't need
Pattern-based filtering: Use wildcards to hide entire categories of tools
Reduce context usage: Significantly decrease token consumption by exposing only necessary tools

🏗️ Architecture

┌────────────────────────┐
│ 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 Funnel:

Connects to multiple MCP servers as a client
Receives all tools from each server
Applies your filtering rules
Exposes only the filtered tools to clients
Routes tool calls to the appropriate backend server

🚀 Features

Multi-Server Aggregation: Connect to any number of MCP servers
Tool Namespacing: Automatic prefixing prevents naming conflicts (github__create_issue, memory__store_memory)
Flexible Filtering: Show/hide tools using wildcard patterns
Granular Control: Filter individual tools that servers don't allow you to disable
Context Optimization: Reduce MCP tool context usage by 40-60% through selective filtering
Custom Transports: Supports stdio-based MCP servers (Docker, NPX, local binaries)
Server Log Prefixing: Clear identification of which server is logging what
Dynamic Tool Discovery: Experimental feature for reducing initial context usage (see limitations)
Core Tools Mode: Ultra-minimal context mode exposing only selected MCP Funnel tools with dynamic bridging (95%+ context reduction)

💡 Why Use MCP Funnel?

The Context Problem

A typical MCP setup might expose:

GitHub MCP: ~70 tools
Memory MCP: ~30 tools
Filesystem MCP: ~15 tools
Total: 115+ tools consuming 40k tokens

Many of these tools are rarely used:

Workflow management tools
Team/organization tools
Debug and diagnostic tools
Dashboard interfaces
Advanced embedding operations

Or to "speak" with chat:

Before

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%)

After

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

Then use it:

> 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.

🔧 Installation

Installing Custom Commands

MCP Funnel supports dynamically installing additional commands from npm packages. You can install commands globally to your user directory (~/.mcp-funnel/packages) where they'll be available across all your projects.

Using the `manage_commands` tool

manage_commands is a built-in MCP Funnel tool that installs, updates, and removes command packages without requiring a separate CLI wrapper. The tool is exposed by default as long as exposeCoreTools is unset (or explicitly includes manage_commands).

Example install request through bridge_tool_request (Claude, Codex CLI, etc.):

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

Supported payload fields:

action: install, update, or uninstall (required).
package: npm package spec or previously installed command name (required).
version: optional version (install only) — e.g., "1.2.3".
force: boolean flag to reinstall even if already present (install only).
removeData: boolean flag to delete cached data (uninstall only).

Responses include structured details about the command, any discovered tools, and whether a hot reload succeeded. When running inside an MCP client you can call the tool directly; no additional CLI plumbing is necessary.

Command Discovery

User-installed commands are automatically discovered from ~/.mcp-funnel/packages/node_modules/ and loaded alongside built-in commands. They respect your configuration:

If commands.list is specified, only whitelisted commands are loaded
Commands can be hidden using hideTools patterns
Tools from commands are filtered by exposeTools patterns

⚙️ Configuration

MCP Funnel supports two ways to specify configuration:

Implicit (default): Looks for .mcp-funnel.json in the current working directory
```
npx mcp-funnel  # Uses ./.mcp-funnel.json
```
Explicit: Specify a custom config file path
```
npx mcp-funnel /path/to/config.json
```
User Base Config (merged automatically)

If present, ~/.mcp-funnel/.mcp-funnel.json is merged with the project config. Project values override user base values. Arrays are replaced (no concatenation).

Create a .mcp-funnel.json file in your project directory:

{
  "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"
  ]
}

Passing secrets / environment variables example: GitHub MCP

Here's how simple it is to configure GitHub MCP with secure token handling:

.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

That's it! The secretProviders automatically loads your token from .env, keeping it secure and out of your config files.

Configuration Options

servers: Record of MCP servers to connect to (server name as key)
- Key: Server name (used as tool prefix)
- command: Command to execute
- args: Command arguments (optional)
- env: Environment variables (optional, deprecated - use secretProviders instead)
- secretProviders: Array of secret provider configurations for secure environment variable management (recommended)
defaultSecretProviders: Default secret providers applied to all servers (optional)
defaultPassthroughEnv: Environment variables passed to all servers by default (optional)
alwaysVisibleTools: Patterns for tools that are always exposed, bypassing discovery mode (optional)
exposeTools: Include patterns for external tools to expose (optional)
hideTools: Exclude patterns for external tools to hide (optional)
exposeCoreTools: Include patterns for internal MCP Funnel tools (optional, defaults to all enabled)

alwaysVisibleTools vs exposeTools

Use exposeTools alone when you want a tool visible at startup. No duplication in alwaysVisibleTools is needed for server-backed tools.
Use alwaysVisibleTools when you want a server tool to bypass all gating (expose/hide, future pattern changes). It wins over hideTools. You do not need to repeat it in exposeTools.
Commands: Command tools are exposed using their tool names directly (e.g., npm_lookup, ts-validate) or with wildcards (e.g., npm_*) in exposeTools/hideTools patterns.

Filtering Patterns

Patterns match against the prefixed tool names (serverName__toolName) and support wildcards (*):

Individual tools:

github__get_team_members - Hide specific tool from GitHub server
memory__check_database_health - Hide specific tool from Memory server

Wildcard patterns:

memory__dashboard_* - All dashboard tools from Memory server
github__debug_* - All debug tools from GitHub server
*__workflow_* - All workflow-related tools from any server
memory__ingest_* - All ingestion tools from Memory server
*__list_* - All list tools from any server

Common filtering examples:

"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
]

Note: Always use the server prefix (e.g., github__, memory__) to target specific servers' tools. Use *__ at the beginning to match tools from any server.

Core Tool Filtering

MCP Funnel includes internal tools for discovery and bridging. Control which core tools are exposed using exposeCoreTools:

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

Available core tools:

discover_tools_by_words - Search for tools by keywords
get_tool_schema - Get input schema for tools
bridge_tool_request - Execute tools dynamically
load_toolset - Load predefined tool patterns

If exposeCoreTools is not specified, all core tools are enabled by default.

🚀 Usage

With Claude Code CLI

Add to your configuration (e.g. path/to/your/project/.mcp.json):

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

This will use .mcp-funnel.json from your current working directory. To use a custom config path:

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

With Google Gemini

Add to your configuration (e.g. path/to/your/project/.gemini/settings.json):

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

With Codex CLI

Add to your configuration (e.g. ~/.codex/config.toml):

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

CLI Onboarding

Kick off the guided migration flow to consolidate existing CLI configs:

npx mcp-funnel init

This command:

Scans typical configuration files for Claude Code/Gemini (.mcp.json, .gemini/settings.json), Claude Desktop (~/.claude.json), and Codex (~/.codex/config.toml).
Lists every MCP server it finds and lets you pick which ones should move into .mcp-funnel.json.
Merges the selected servers into .mcp-funnel.json, creating the file with recommended defaults when needed.
Rewrites each client config so that only a single mcp-funnel entry remains, pointing at the merged configuration.

Every write is gated behind an explicit confirmation, so you can review the proposed changes before they land.

Example Prompts

Once configured, you can use natural language to interact with your aggregated tools:

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

This works seamlessly because MCP Funnel aggregates your GitHub server's tools with proper namespacing!

🎮 Tool Visibility Control

MCP Funnel provides a three-tier visibility system for managing which tools are exposed:

1. Always Visible Tools (`alwaysVisibleTools`)

Tools matching these patterns are always exposed from startup, even when using the dynamic discovery pattern (empty allowlist). Perfect for critical tools you always want available.

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

2. Discoverable Tools (`exposeTools`)

When using an empty allowlist (exposeTools: []), these tools are hidden initially but can be discovered and enabled dynamically via load_toolset. When allowlisted in exposeTools, they're visible from startup.

3. Hidden Tools (`hideTools`)

Tools matching these patterns are never exposed, regardless of other settings.

Dynamic Discovery

To start with a minimal surface and enable tools on demand:

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

Runtime flow:

Search: discover_tools_by_words with keywords (e.g., "context7").
Enable: load_toolset with explicit tool names or patterns (e.g., ["context7__resolve_library_id", "context7__get-library-docs"]).
Call: Use the enabled tools normally.

🚀 Core Tools Mode (Ultra-Low Context)

Core Tools Mode allows you to expose only MCP Funnel's internal tools for dynamic discovery. When you set exposeCoreTools to a minimal set, MCP Funnel can expose as few as 3 tools instead of 100+:

discover_tools_by_words: Search for tools by keywords
get_tool_schema: Get input schema for any tool
bridge_tool_request: Execute any tool dynamically

How It Works

{
  "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"
  ]
}

Usage Examples

Simple workflow:

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

Step-by-step workflow:

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"}}

Benefits

Full functionality: All tools remain accessible
Smart discovery: Claude can find and use tools naturally
Works today: No waiting for Claude Code updates

Trade-offs

Less discoverable (tools aren't visible upfront)
Slight overhead for discovery/schema steps
Best for scenarios where you use <10% of available tools

🔍 Dynamic Tool Discovery (Experimental)

MCP Funnel includes a discover_tools_by_words tool that allows searching for tools by keywords. However, this feature currently has limited utility:

⚠️ Current Limitations

Claude Code CLI does not support dynamic tool updates. Once a session starts, the tool list is fixed. This means:

The discover_tools_by_words tool can find matching tools
It can "enable" them in MCP Funnel's internal state
But Claude won't see newly enabled tools until you restart the session

We're eagerly waiting for these issues to be resolved:

claude-code#7519 - Dynamic tool discovery support
claude-code#4118 - Runtime tool updates

Once these features land, dynamic discovery will significantly reduce initial context usage by loading only the tools you need on-demand.

🔒 Security Considerations

🔐 Secret Management

MCP Funnel includes a secure secret management system that follows the principle of least privilege. Instead of exposing all environment variables to MCP servers, you can use secret providers to control exactly which secrets each server receives.

Quick example:

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

Key benefits:

Minimal environment variable exposure to child processes
Multiple provider types (dotenv, process, inline) with precedence rules
Built-in security filtering to prevent credential leakage
Centralized secret management across all your MCP servers

📖 See the complete Secret Management guide →

Infrastructure Security

Filesystem access: Be careful with filesystem server paths
Docker permissions: Ensure proper Docker socket access if using containerized servers
Network isolation: Consider running in isolated environments for sensitive operations

🗺️ Roadmap

Connection retry logic for resilient server management
Health monitoring and status reporting
Graceful degradation when servers fail
Structured logging with configurable levels
Metrics and performance monitoring
WebSocket transport support
Full dynamic tool discovery (blocked on Claude Code CLI support)

🛠️ Development

For local development setup, debugging, and testing:

📖 See the Development Guide →

🤝 Contributing

Contributions are welcome! Key areas needing work:

Error handling: Make MCP Funnel resilient to server failures
Testing: Add comprehensive test coverage for other clients than Claude Code
Logging: Implement structured logging

📄 License

MIT - See LICENSE file in the repository root

mcp-funnel

Documentation