MCP Filter
A proxy MCP (Model Context Protocol) server that filters the upstream tool surface to just the tools you need.
What is MCP Filter?
MCP Filter is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to proxy mcp (model context protocol) server that filters the upstream tool surface to just the tools you need.
A proxy MCP (Model Context Protocol) server that filters the upstream tool surface to just the tools you need.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A proxy MCP (Model Context Protocol) server that filters the
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mcp-filterConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use MCP Filter
MCP Filter is a lightweight proxy MCP server that sits between your AI client and one or more upstream MCP servers, exposing only the subset of tools you explicitly allow. By trimming an upstream server's tool surface — for example reducing a Supabase server from 20+ tools to just three — it can cut the token overhead of tool descriptions by more than 90%, making AI sessions faster and cheaper. It supports both stdio and HTTP (SSE) upstream connections, tool allowlisting by name, deny patterns via regex, and optional tool renaming via a configurable prefix.
Prerequisites
- Python 3.11 or higher installed
- pip or uv package manager
- At least one upstream MCP server to proxy (e.g., a Supabase or filesystem MCP server)
- An MCP-compatible client such as Claude Desktop or Cursor
Install mcp-filter
Install via pip or uv. The uv method lets you run it directly with uvx without a permanent installation.
# With pip:
pip install mcp-filter
# With uv (no permanent install):
uvx mcp-filter --versionIdentify the tools you want to expose
Start the upstream MCP server on its own and list its available tools, then decide which ones your AI client actually needs. This determines your allowlist.
Run mcp-filter wrapping an upstream server
Launch mcp-filter in stdio mode, pointing it at the upstream server binary. Use -a to specify the tool names to allow. This example wraps the Supabase MCP server and exposes only three tools.
mcp-filter run \
-t stdio \
--stdio-command npx \
--stdio-arg "-y @supabase/mcp-server-supabase@latest --access-token YOUR_TOKEN" \
-a "execute_sql,list_tables,get_project"Use environment variables instead of flags (optional)
All CLI flags have MF_-prefixed environment variable equivalents, which is convenient when embedding the configuration in claude_desktop_config.json.
export MF_TRANSPORT=stdio
export MF_ALLOW_TOOLS=execute_sql,list_tables,get_project
export MF_STDIO_COMMAND=npx
export MF_STDIO_ARGS="-y @supabase/mcp-server-supabase@latest --access-token YOUR_TOKEN"
mcp-filter runConfigure Claude Desktop to use mcp-filter
Add mcp-filter as the MCP server in your client config. The client sees only the filtered tool surface.
{
"mcpServers": {
"filtered-supabase": {
"command": "mcp-filter",
"args": [
"run",
"-t", "stdio",
"--stdio-command", "npx",
"--stdio-arg", "-y @supabase/mcp-server-supabase@latest --access-token YOUR_TOKEN",
"-a", "execute_sql,list_tables,get_project"
],
"env": {}
}
}
}MCP Filter Examples
Client configuration
Claude Desktop config that wraps the Supabase MCP server and exposes only three tools, reducing tool-description token cost from ~20k to ~2k.
{
"mcpServers": {
"filtered-supabase": {
"command": "mcp-filter",
"args": [
"run",
"-t", "stdio",
"--stdio-command", "npx",
"--stdio-arg",
"-y @supabase/mcp-server-supabase@latest --access-token YOUR_SUPABASE_TOKEN",
"-a", "execute_sql,list_tables,get_project"
],
"env": {}
}
}
}Prompts to try
With only the relevant tools exposed, prompts are cleaner and the AI is less likely to pick the wrong tool.
- "List all tables in my Supabase database"
- "Run a SQL query to count the number of users created in the last 7 days"
- "What tools are currently available through this MCP server?"
- "Enable the health check tool and show the current server status"Troubleshooting MCP Filter
No tools appear in the AI client after configuring mcp-filter
Check that the tool names passed to -a exactly match the names the upstream server exposes (case-sensitive). Run the upstream server independently and list its tools to get the exact names.
Upstream server fails to start when launched by mcp-filter
Test the upstream command in isolation first (e.g., run 'npx -y @supabase/mcp-server-supabase@latest --access-token YOUR_TOKEN' directly). Fix any credential or path issues before adding mcp-filter to the chain.
MF_ environment variables are not picked up
Environment variables must be set in the same process that runs mcp-filter. When using claude_desktop_config.json, place them in the 'env' object of the server config rather than relying on your shell profile.
Frequently Asked Questions about MCP Filter
What is MCP Filter?
MCP Filter is a Model Context Protocol (MCP) server that proxy mcp (model context protocol) server that filters the upstream tool surface to just the tools you need. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install MCP Filter?
Follow the installation instructions on the MCP Filter GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with MCP Filter?
MCP Filter works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is MCP Filter free to use?
Yes, MCP Filter is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
MCP Filter Alternatives — Similar Developer Tools Servers
Looking for alternatives to MCP Filter? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up MCP Filter in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use MCP Filter?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.