Tool Filter

You run a configurable MCP proxy that filters tools from upstream MCP servers using regex patterns. It helps you control which tools reach your agents, reducing context bloat while keeping upstream behavior intact. You can quickly discover available tools, apply deny lists, and forward allowed calls to the upstream MCP server with minimal latency.

How to use

Set up a proxy that sits between your MCP client and an upstream MCP server. You can filter tools by patterns, pass authentication headers, and discover what tools exist before applying filters.

Basic HTTP/SSE usage filters tools from an HTTP MCP upstream and forwards the rest transparently. Use a deny list to block specific tool names or patterns.

If you prefer running a local stdio MCP server, you can spawn the upstream server as a child process and apply the same filters. This is useful when you want to integrate with existing local MCP servers or development workflows.

When you need to see what tools are available before deciding on filters, you can list tools from the upstream server in various formats (table, JSON, or a simple comma-separated list). This helps you compose precise deny patterns.

If you require authentication, you can pass custom headers to the upstream server for HTTP modes and environment variables for stdio modes. This keeps credentials tucked away in your environment while you manage access to upstream resources.

How to install

Prerequisites: ensure you have Node.js version 20.0.0 or higher installed on your system.

Install or run the MCP proxy that filters tools using the following commands. You will need either an HTTP/SSE upstream or a stdio upstream depending on your setup.

# For HTTP/SSE MCP servers
npx @respawn-app/tool-filter-mcp --upstream <url> --deny <patterns>

# For stdio MCP servers
npx @respawn-app/tool-filter-mcp --upstream-stdio --deny <patterns> -- <command> [args...]

Additional content

Configuration examples shown below illustrate how to wire the proxy for both HTTP and stdio modes. There are multiple concrete snippets demonstrating common scenarios, including filtering with multiple patterns, listing tools, and using environment variables or authentication headers.

Important notes:

• The HTTP configuration uses a URL to connect to an upstream SSE HTTP MCP server and an optional set of deny patterns.
• The stdio configuration spawns a local upstream MCP server and forwards its output after applying filters. The command and arguments after the -- separator represent the actual upstream process invocation.

Security and troubleshooting

• Use precise regex patterns for deny lists to minimize accidental tool blocking. Start with narrow patterns and broaden them only after testing.

• When using headers or environment variables, ensure credentials are stored securely in your environment and are not committed to source control.

• If the proxy cannot connect to upstream, verify network access, upstream URL or command, and that the upstream server is running.

Tools and capabilities

• Tool Filtering: Block specific tools using regex patterns
• Tool Discovery: List available tools with multiple output formats (table, JSON, names)
• Header Pass-Through: Add custom HTTP headers for authentication
• Zero Latency: Cached tool list, minimal overhead
• Fail-Fast: Immediate error on connection issues or invalid patterns
• Transparent Proxying: Forwards allowed tool calls to upstream without modification

Available tools

tool filtering

Block specific tools from upstream by regex patterns to minimize context pollution.

tool discovery

List available tools in formats like table, JSON, or names to help you craft filters.

header pass-through

Forward custom HTTP headers to the upstream server for HTTP mode authentication.

zero latency

Cache the tool list to minimize overhead and latency in tool discovery.

fail-fast

Fail fast on connection issues or invalid patterns to provide immediate feedback.

transparent proxying

Forward allowed tool calls to upstream without modifying their payloads.