filter-mcp-tools

filter-mcp-tools is a deterministic MCP tool-list relay. It connects to one HTTP, legacy SSE, or stdio MCP server, lets an operator inspect the complete catalog, and exposes a filtered stdio MCP server to Claude Code, Codex, or any other local MCP client.

Behavior

• Exact, glob, and regular-expression include/exclude rules match full tool names.

• Include rules are ORed. When any include rule exists, unmatched tools are removed.

• Exclude rules are ORed and always win over include rules.

• tools/list returns only retained tools; direct tools/call attempts for hidden tools are rejected before reaching the upstream server.

• A zero-tool result fails closed unless --allow-empty is explicit.

• Tool pagination and notifications/tools/list_changed are handled.

• Prompts, resources, subscriptions, and completion requests pass through unchanged when the upstream advertises them.

This is deterministic name filtering, not semantic retrieval. It is designed for auditable allowlists and denylists.

Related MCP server: mcp-facade

Recommended workflow

First inspect the upstream catalog without a filter:

npx -y filter-mcp-tools@latest list \
  --url https://mcp.example.com/mcp \
  --names-only

Then preview both sides of a proposed rule before exposing the relay:

npx -y filter-mcp-tools@latest list \
  --url https://mcp.example.com/mcp \
  --include-glob 'docs_*' \
  --exclude-regex '/delete|remove/i' \
  --show kept

npx -y filter-mcp-tools@latest list \
  --url https://mcp.example.com/mcp \
  --include-glob 'docs_*' \
  --exclude-regex '/delete|remove/i' \
  --show removed

Move the accepted rules into a JSON config and use the same file for list and proxy. This keeps review and runtime behavior identical.

Install and test

npm install --global filter-mcp-tools
filter-mcp-tools --version

To develop locally:

git clone https://github.com/mapix/filter-mcp-tools.git
cd filter-mcp-tools
npm ci
npm run check

One-off use does not require a global install:

npx -y filter-mcp-tools@latest --help

Inspect before filtering

List every tool from an HTTP MCP endpoint:

filter-mcp-tools list \
  --url https://mcp.example.com/mcp \
  --header-env Authorization=MCP_AUTHORIZATION

Preview a filter and include the match explanation and complete MCP schemas:

filter-mcp-tools list \
  --url https://mcp.example.com/mcp \
  --header-env Authorization=MCP_AUTHORIZATION \
  --include-glob '*docs*' \
  --exclude-regex '/delete|remove/i' \
  --json

Useful output controls:

--show kept       # all, kept, or removed
--names-only      # one selected tool name per line
--json            # schemas plus includedBy/excludedBy explanations

Run as a relay

filter-mcp-tools proxy \
  --url https://mcp.example.com/mcp \
  --header-env Authorization=MCP_AUTHORIZATION \
  --include-glob '*docs*' \
  --exclude-regex '/delete|remove/i'

The relay speaks MCP over stdout/stdin, so stdout is reserved for protocol frames. Diagnostics go to stderr and never include resolved header values.

Claude Code example (pin the version in long-lived configuration):

claude mcp add -s user filtered-docs -- \
  npx -y filter-mcp-tools@0.1.0 proxy --config /absolute/path/filter.json

Codex uses the same stdio command:

[mcp_servers.filtered-docs]
command = "npx"
args = ["-y", "filter-mcp-tools@0.1.0", "proxy", "--config", "/absolute/path/filter.json"]

Clients with native per-server tool filtering can use that instead and avoid the extra process.

JSON configuration

Configuration avoids long client command lines and supports secret sources without shell evaluation:

{
  "upstream": {
    "transport": "http",
    "url": "https://mcp.example.com/mcp",
    "headers": {
      "Authorization": {
        "env": "MCP_TOKEN",
        "prefix": "Bearer "
      },
      "x-api-key": {
        "command": [
          "/usr/bin/security",
          "find-generic-password",
          "-s",
          "my-mcp-token",
          "-w"
        ]
      }
    }
  },
  "filter": {
    "include": ["docs_read"],
    "includeGlob": ["docs_*"],
    "includeRegex": ["/^wiki_(read|search)$/"],
    "exclude": [],
    "excludeGlob": ["*_admin"],
    "excludeRegex": ["/delete|remove/i"],
    "ignoreCase": false
  },
  "allowEmpty": false
}

Run it with filter-mcp-tools list --config filter.json to preview, then change list to proxy. Command secret sources use execFile, never a shell; only use configuration files you trust.

examples/filter.example.json is a copyable starting point.

Literal header values support ${ENV_VAR} interpolation. Avoid putting secrets in CLI arguments because process listings and shell history can expose them.

Use --transport sse only for a legacy HTTP+SSE upstream. Streamable HTTP is the default for --url; the relay exposed to the local client remains stdio in both cases.

Stdio upstream

filter-mcp-tools list \
  --transport stdio \
  --stdio-command node \
  --stdio-arg ./server.mjs \
  --include-regex '/^docs_/'

The JSON equivalents are upstream.command, args, cwd, and env.

Scope and security

This relay is a client-side visibility and invocation boundary. A user who controls the relay configuration can change its filters, so it does not replace authorization on the upstream MCP server. Enforce real access through server-, key-, team-, or identity-bound policy, then use this package to narrow the already-authorized set.

See SECURITY.md for vulnerability reporting.