mcp-filter

MCP Filter acts as a drop-in proxy in front of an existing MCP server to selectively expose only the tools you need. By filtering tools, it reduces the token surface area that clients must process, helping conserve context length during sessions. You can specify an allowlist of tool names (or patterns) and optionally add a prefix to exposed tool names for clarity. Use it when you want to retain upstream capabilities while omitting costly or unnecessary tools.

To use it, configure mcp-filter with the upstream MCP server you want to wrap (for example, a Supabase MCP server) and list the tools you wish to expose, such as execute_sql, list_tables, or get_project. The wrapper then proxies calls to the upstream server, only exposing the allowed tools to clients. You can run mcp-filter via stdio (in-process) or wrapped transports like uvx, and you can supply the upstream command and arguments directly in the configuration or via environment variables. The health tool option and regex-based deny lists provide additional observability and safety guarantees.

Prerequisites:

• Python 3.10+ (3.11 recommended) or a runtime supporting uv/x (if using uvx)
• Access to install Python packages or the ability to run binaries from your environment

Install via pip (recommended for Python users):

pip install mcp-filter

Install via uvx (faster, ephemeral execution):

# Quick check of version (example)
uvx mcp-filter --version

From source (development):

# Optional: set up Python env and install dev dependencies
pyenv install 3.11.9
pyenv local 3.11.9
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Run a wrapped MCP server example (as shown in Quick Start):

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"

You can also use uvx for ephemeral execution of the wrapped command, or wrap any existing MCP server with the filter by adjusting the upstream command and allowed tools.

Tips and notes:

• The default configuration exposes a minimal set of tools; adjust the MF_ALLOW_TOOLS or --allow-tool flags to tailor the surface.
• If you need to inspect token usage, enable token estimates with MF_SHOW_TOKEN_ESTIMATES=1 (or the equivalent CLI flag) to see rough token costs.
• The health tool can be enabled to monitor availability; enable MF_INCLUDE_HEALTH_TOOL=1 if you rely on health checks.
• Use a prefix (MF_RENAME_PREFIX) to avoid name collisions when wrapping multiple upstream MCP servers.
• Secrets passed as CLI arguments or in headers are not logged by the filter; however, be mindful of how upstream commands are composed to avoid leaking tokens into logs.
• Regex-based deny lists (MF_DENY_PATTERNS) provide an extra safety layer to block unintended tool names.