@jorgemf/mcp-filter-tools

@jorgemf/mcp-filter-tools

A TypeScript MCP (Model Context Protocol) proxy server that filters upstream tools using allowlist patterns to dramatically reduce token consumption.

Features

• 🎯 Allowlist Filtering: Expose only the tools you need using exact names or regex patterns
• 🔌 Multi-Transport Support: Works with stdio, SSE, and HTTP transports
• 📉 Token Reduction: Reduce context token usage by 70-90% by filtering unnecessary tools
• 🛠️ Easy CLI: Simple command-line interface for quick configuration
• 📦 TypeScript: Fully typed for better developer experience

Installation

npm install @jorgemf/mcp-filter-tools

Or use directly with npx:

npx @jorgemf/mcp-filter-tools [options]

Usage

Basic Example (stdio transport)

Filter a local MCP server to expose only specific tools:

npx @jorgemf/mcp-filter-tools \
  --transport stdio \
  --stdio-command npx \
  --stdio-arg -y \
  --stdio-arg @modelcontextprotocol/server-filesystem@latest \
  --allow-tool read_file \
  --allow-tool list_directory

Example with Regex Patterns

Allow tools matching patterns:

npx @jorgemf/mcp-filter-tools \
  --transport stdio \
  --stdio-command npx \
  --stdio-arg -y \
  --stdio-arg @supabase/mcp-server-supabase@latest \
  --allow-pattern "^execute_" \
  --allow-pattern "^list_" \
  --allow-tool get_project

Example with HTTP/SSE Transport

Filter a remote MCP server:

npx @jorgemf/mcp-filter-tools \
  --transport sse \
  --http-url http://localhost:3000/sse \
  --allow-tool tool1 \
  --allow-tool tool2

CLI Options

Option	Alias	Description	Default
--transport <type>	-t	Transport type: stdio, sse, or http	stdio
--stdio-command <cmd>		Command to execute for stdio transport
--stdio-arg <arg>		Arguments for stdio command (can be repeated)	[]
--http-url <url>		URL for HTTP/SSE transport
--allow-tool <name>	-a	Exact tool name to allow (can be repeated)	[]
--allow-pattern <regex>		Regex pattern for tool names (can be repeated)	[]

Note: At least one --allow-tool or --allow-pattern must be specified.

Configuration in MCP Clients

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "filtered-filesystem": {
      "command": "npx",
      "args": [
        "@jorgemf/mcp-filter-tools",
        "--transport", "stdio",
        "--stdio-command", "npx",
        "--stdio-arg", "-y",
        "--stdio-arg", "@modelcontextprotocol/server-filesystem@latest",
        "--allow-tool", "read_file",
        "--allow-tool", "write_file",
        "--allow-pattern", "^list_"
      ]
    }
  }
}

Note: Claude Desktop may display capabilities: none for this server. This is normal and expected - it means the server has no additional capabilities beyond tools (no prompts, resources, etc.). Your filtered tools will still be available and functional. See CLAUDE_DESKTOP.md for details.

Cline/Continue Configuration

Similar configuration in your MCP settings file.

How It Works

• Proxy Architecture: Acts as a transparent proxy between MCP clients and upstream servers
• Tool Filtering: Intercepts tools/list requests and filters tools based on allowlist
• Request Forwarding: Forwards tools/call requests to upstream (only for allowed tools)
• Token Savings: By exposing fewer tools, dramatically reduces context window usage

Examples

Filtering Supabase MCP Server

Reduce 29 tools (~20.8k tokens) to 3 tools (~1.9k tokens) - 91% reduction:

npx @jorgemf/mcp-filter-tools \
  --transport stdio \
  --stdio-command npx \
  --stdio-arg -y \
  --stdio-arg @supabase/mcp-server-supabase@latest \
  --stdio-arg --access-token \
  --stdio-arg YOUR_TOKEN \
  --allow-tool execute_sql \
  --allow-tool list_tables \
  --allow-tool get_project

Filtering Filesystem Server

Expose only read operations:

npx @jorgemf/mcp-filter-tools \
  --transport stdio \
  --stdio-command npx \
  --stdio-arg -y \
  --stdio-arg @modelcontextprotocol/server-filesystem@latest \
  --allow-pattern "^read_" \
  --allow-pattern "^list_"

Programmatic Usage

You can also use the library programmatically:

import { MCPFilterProxy } from '@jorgemf/mcp-filter-tools';

const proxy = new MCPFilterProxy({
  transport: {
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem@latest'],
  },
  filter: {
    allowTools: ['read_file', 'write_file'],
    allowPatterns: ['^list_'],
  },
});

await proxy.start();

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests (watch mode)
npm test

# Run tests (single run)
npm run test:ci

# Run only unit tests
npm run test:unit

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

# Run all tests
npm run test:all

# Generate coverage report
npm run test:coverage

# Lint
npm run lint

# Format
npm run format

See TEST_GUIDE.md for detailed testing documentation.

Comparison with Other Tools

Feature	@jorgemf/mcp-filter-tools	mcp-filter (Python)	@respawn-app/tool-filter-mcp
Language	TypeScript	Python	TypeScript
Allowlist	✅	✅	❌
Denylist	❌	✅	✅
stdio transport	✅	✅	❌
HTTP/SSE transport	✅	✅	✅
Regex patterns	✅	✅	✅
Tool prefixing	❌	✅	❌
Health check	❌	✅	❌

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Credits

Inspired by:

• mcp-filter - Python MCP filter proxy
• @respawn-app/tool-filter-mcp - TypeScript tool filter