Tool Filter MCP

🚀 tool-filter-mcp

An MCP proxy server that filters tools from upstream MCP servers via a regex-based deny list.

Maintained: ✅ Yes (Fall 2025)

🚀 Quick Start

This tool-filter-mcp is an MCP proxy server that effectively filters tools from upstream MCP servers using a regex-based deny list.

✨ Features

• Tool Filtering: Block specific tools using regex patterns.
• 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.

📦 Installation

npx @respawn-app/tool-filter-mcp --upstream <url> --deny <patterns>

💻 Usage Examples

Basic Usage

Filter tools matching .*_file$ pattern:

npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --deny ".*_file$"

Advanced Usage

Multiple Patterns

Use comma-separated patterns:

npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --deny "get_file_text,create_new_file,replace_text"

With Authentication Headers

Add custom headers for authentication:

npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --header "Authorization: Bearer your-token-here" \
  --header "X-API-Key: your-api-key"

Headers support environment variable expansion (if not yet expanded by your app):

npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --header "Authorization: Bearer $AUTH_TOKEN"

With Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "filtered-server": {
      "command": "npx",
      "args": [
        "@respawn-app/tool-filter-mcp",
        "--upstream",
        "http://localhost:3000/sse",
        "--deny",
        "dangerous_tool_1,dangerous_tool_2"
      ],
      "type": "stdio"
    }
  }
}

With authentication headers (supports environment variable expansion):

{
  "mcpServers": {
    "filtered-server": {
      "command": "npx",
      "args": [
        "@respawn-app/tool-filter-mcp",
        "--upstream",
        "http://localhost:3000/sse",
        "--header",
        "Authorization: Bearer ${API_TOKEN}",
        "--header",
        "X-Custom-Header: $CUSTOM_VALUE"
      ],
      "type": "stdio"
    }
  }
}

📚 Documentation

CLI Options

Requirements

• Node.js >= 20.0.0
• Upstream MCP server with SSE transport

📄 License

MIT

Why use this?

For effective context engineering, we want to minimize useless tokens. Most major agents right now (e.g. Claude Code) do NOT remove tool descriptions from the context. Even though the tool is completely denied and unused, the model will still get its entire description and still try to call the tool (and get error messages). For big MCPs, such as github, supabase, jetbrains IDE, atlassian, this is catastrophic to the context and leads to context pollution by 40 - 60k of useless tokens. You wanted your agent to be able to see jira ticket descriptions? Please also have these 44 useless tools to edit assignees on confluence pages.

This MCP completely solves the issue without introducing any overhead. This project is fully vibe - coded with claude. Contributions welcome!