mcp-tool-filter

A generic MCP proxy that filters which tools are exposed from a remote MCP server. Reduces context window token usage by only loading the tools you actually need.

The Problem

Remote MCP servers (Linear, GitHub, Notion, etc.) expose all their tools to your AI coding assistant. A single server can blast 20,000+ tokens of tool definitions into your context window — even if you only use 5 of them. That's 10% of your context gone before you type a single message.

The Solution

mcp-tool-filter sits between your AI client and the remote MCP server as a lightweight stdio proxy. It fetches all tools from upstream but only exposes the ones you whitelist. Everything else is filtered out, saving thousands of tokens per conversation.

┌─────────────┐     stdio      ┌──────────────────┐     HTTP      ┌──────────────┐
│  Claude Code │ ◄────────────► │  mcp-tool-filter  │ ◄──────────► │  Remote MCP   │
│  (6 tools)   │                │  (filters tools)  │              │  (29 tools)   │
└─────────────┘                └──────────────────┘              └──────────────┘

Quick Start

Interactive Setup (Recommended)

npx mcp-tool-filter add

This walks you through:

1. Enter the upstream MCP server URL
2. Confirm the server name
3. Authenticate (if needed — opens browser automatically)
4. Select which tools to expose from the full list
5. Choose where to save the config

Manual Setup

Add to your .mcp.json:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y", "mcp-tool-filter",
        "--url", "https://mcp.linear.app/mcp",
        "--tools", "get_issue", "update_issue", "create_issue"
      ]
    }
  }
}

Or with the Claude Code CLI:

claude mcp add linear -- npx -y mcp-tool-filter \
  --url https://mcp.linear.app/mcp \
  --tools get_issue update_issue create_issue

Usage

mcp-tool-filter --url <upstream-mcp-url> [--name <server-name>] [--tools <tool1> <tool2> ...]

Options

Flag	Required	Description
--url	Yes	The upstream MCP server URL
--tools	No	Space-separated list of tool names to expose. If omitted, all tools are passed through
--name	No	Server name for token storage. Auto-derived from URL if not provided

Updating Tool Selection

Need to add or remove tools from an existing server? Run update with the server name from your .mcp.json:

npx mcp-tool-filter update linear

This will:

1. Read the existing config from your .mcp.json
2. Connect to the upstream server
3. Show all available tools with your current selection pre-checked
4. Update the config with your new selection

Pass-through Mode

Omit --tools to proxy all tools without filtering (useful if you only need the OAuth/auth handling):

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-tool-filter", "--url", "https://mcp.linear.app/mcp"]
    }
  }
}

Authentication

mcp-tool-filter handles OAuth automatically:

1. First run: The upstream server returns 401, the proxy opens your browser for OAuth login, waits for the callback, and saves the tokens
2. Subsequent runs: Stored tokens are reused automatically — no browser needed

Tokens are persisted in ~/.mcp-tool-filter/<server-name>.json.

To re-authenticate, delete the token file:

rm ~/.mcp-tool-filter/linear.json

Servers Without OAuth

If the upstream server doesn't require authentication, the proxy connects directly — no OAuth flow needed.

Examples

Linear (6 tools instead of 29)

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y", "mcp-tool-filter",
        "--url", "https://mcp.linear.app/mcp",
        "--tools", "get_issue", "update_issue", "create_issue",
        "list_issues", "list_issue_labels", "get_project"
      ]
    }
  }
}

Multiple Filtered Servers

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y", "mcp-tool-filter",
        "--url", "https://mcp.linear.app/mcp",
        "--tools", "get_issue", "update_issue"
      ]
    },
    "another-server": {
      "command": "npx",
      "args": [
        "-y", "mcp-tool-filter",
        "--url", "https://another-mcp-server.com/mcp",
        "--tools", "read_document", "search"
      ]
    }
  }
}

How It Works

1. Starts as a stdio MCP server (what your AI client connects to)
2. Connects to the upstream server via Streamable HTTP (with SSE fallback)
3. On tools/list — fetches all tools from upstream, returns only the allowed ones
4. On tools/call — forwards the call to upstream, returns the response unchanged
5. Handles OAuth automatically with token persistence

Transport Support

Transport	Status
Streamable HTTP	Supported (preferred)
Server-Sent Events (SSE)	Supported (fallback)
stdio upstream	Not supported (use for local servers directly)

Compatibility

Works with any MCP client that supports stdio servers:

• Claude Code
• Claude Desktop
• Cursor
• Windsurf
• Any MCP-compatible client

Development

git clone https://github.com/kais-radwan/mcp-tool-filter.git
cd mcp-tool-filter
npm install
npm run build

Test locally:

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": [
        "/path/to/mcp-tool-filter/dist/index.js",
        "--url", "https://mcp.linear.app/mcp",
        "--tools", "get_issue"
      ]
    }
  }
}

License

MIT