tool-filter-mcp

Servidor proxy MCP que filtra herramientas de servidores MCP ascendentes mediante una lista de denegación basada en regex.

Mantenido: ✅ Sí (Primavera/verano 26)

¿Por qué usar esto?

Para una ingeniería de contexto efectiva, queremos minimizar los tokens inútiles. La mayoría de los agentes principales actuales (p. ej., Claude Code) NO eliminan las descripciones de las herramientas del contexto. Aunque la herramienta esté completamente denegada y sin uso, el modelo seguirá recibiendo su descripción completa y aún así intentará llamar a la herramienta (y recibirá mensajes de error). Para MCPs grandes, como github, supabase, jetbrains IDE, atlassian, esto es catastrófico para el contexto y conduce a una contaminación del contexto de 40-60k de tokens inútiles. ¿Querías que tu agente pudiera ver las descripciones de los tickets de jira? Por favor, ten también estas 44 herramientas inútiles para editar responsables en páginas de confluence.

Este MCP resuelve completamente el problema sin introducir ninguna sobrecarga. ¡Las contribuciones son bienvenidas!

Related MCP server: mcp-tool-filter

Instalación

# 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...]

Uso

Ejemplo básico (HTTP/SSE)

Filtra las herramientas que coincidan con el patrón .*_file$ de un servidor MCP HTTP:

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

Ejemplo básico (stdio)

Filtra herramientas de un servidor MCP stdio local:

npx @respawn-app/tool-filter-mcp \
  --upstream-stdio \
  --deny "dangerous_.*" \
  -- npx my-mcp-server

Con variables de entorno (stdio)

Pasa variables de entorno al servidor stdio ascendente:

npx @respawn-app/tool-filter-mcp \
  --upstream-stdio \
  --env "API_KEY=secret123" \
  --env "DEBUG=true" \
  --deny "admin_.*" \
  -- npx my-mcp-server

Patrones múltiples

Usa patrones separados por comas:

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

Con encabezados de autenticación

Añade encabezados personalizados para la autenticación:

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

Los encabezados admiten la expansión de variables de entorno (si aún no han sido expandidas por tu aplicación):

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

Listar herramientas disponibles

Descubre qué herramientas están disponibles antes de configurar los filtros:

# Default table format
npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --list-tools

# Get comma-separated names for copy-paste
npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --list-tools --format=names

# Get full JSON with schemas
npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --list-tools --format=json

# Preview filtered results
npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --deny ".*_file$" \
  --list-tools --format=names

Con Claude Code

Servidor ascendente HTTP/SSE

Añádelo a tu .mcp.json:

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

Con encabezados de autenticación (admite la expansión de variables de entorno):

{
  "mcpServers": {
    "filtered-http-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",
        "--deny",
        "sensitive_.*"
      ],
      "type": "stdio"
    }
  }
}

Servidor ascendente Stdio

{
  "mcpServers": {
    "filtered-zen": {
      "command": "npx",
      "args": [
        "@respawn-app/tool-filter-mcp",
        "--upstream-stdio",
        "--deny",
        "dangerous_.*,sensitive_.*",
        "--",
        "npx",
        "my-mcp-server"
      ],
      "type": "stdio"
    }
  }
}

Con múltiples argumentos para el servidor ascendente:

{
  "mcpServers": {
    "filtered-stdio-server": {
      "command": "npx",
      "args": [
        "@respawn-app/tool-filter-mcp",
        "--upstream-stdio",
        "--deny",
        "admin_.*",
        "--",
        "node",
        "my-mcp-server.js",
        "--config=config.json",
        "--verbose"
      ],
      "type": "stdio"
    }
  }
}

Con argumentos que comienzan con guiones (como uvx):

{
  "mcpServers": {
    "filtered-uvx-server": {
      "command": "npx",
      "args": [
        "@respawn-app/tool-filter-mcp",
        "--upstream-stdio",
        "--deny",
        "test_.*",
        "--",
        "uvx",
        "--from",
        "git+https://github.com/BeehiveInnovations/zen-mcp-server.git",
        "zen-mcp-server"
      ],
      "type": "stdio"
    }
  }
}

Con variables de entorno para el servidor stdio ascendente:

{
  "mcpServers": {
    "filtered-server-with-env": {
      "command": "npx",
      "args": [
        "@respawn-app/tool-filter-mcp",
        "--upstream-stdio",
        "--env",
        "API_KEY=${MY_API_KEY}",
        "--env",
        "DEBUG=true",
        "--deny",
        "admin_.*",
        "--",
        "npx",
        "my-mcp-server"
      ],
      "type": "stdio"
    }
  }
}

Opciones de CLI

Lista de herramientas

Imprime la lista de herramientas disponibles sin iniciar un servidor proxy

• --list-tools: Lista las herramientas disponibles desde el origen y sale

• --format <type>: Formato de salida para --list-tools (predeterminado: table)

  • table: Tabla legible por humanos con descripciones (truncadas a 100 caracteres)

  • json: Salida JSON completa con esquemas completos

  • names: Nombres de herramientas separados por comas para copiar y pegar fácilmente

Modo de conexión (mutuamente excluyentes)

Para iniciar el servidor proxy, debes especificar exactamente una de las siguientes:

• --upstream <url>: Conectar al servidor MCP HTTP/SSE ascendente

• --upstream-stdio: Generar y conectar al servidor MCP stdio ascendente

  • Requiere comando y argumentos después del separador --

  • Ejemplo: --upstream-stdio -- npx zen-mcp-server

Opciones comunes

• --deny <patterns>: Patrones regex separados por comas para las herramientas a filtrar

Opciones del modo HTTP/SSE

Solo aplicable con --upstream:

• --header <name:value>: Encabezado HTTP personalizado para pasar al servidor ascendente (se puede repetir para múltiples encabezados)

  • Formato: --header "Header-Name: value"

  • Admite expansión de variables de entorno: $VAR o ${VAR}

  • Ejemplo: --header "Authorization: Bearer $TOKEN"

Opciones del modo Stdio

Solo aplicable con --upstream-stdio:

• --env <KEY=value>: Variable de entorno para pasar al servidor stdio ascendente (se puede repetir para múltiples variables)

  • Formato: --env "KEY=value"

  • Ejemplo: --env "API_KEY=secret" --env "DEBUG=true"

• Después del separador --, proporciona el comando y todos sus argumentos

  • Todo lo que sigue a -- se pasa al servidor ascendente

  • Admite argumentos que comienzan con guiones (como --from, --config, etc.)

  • Ejemplo: --upstream-stdio -- uvx --from git+https://... package-name

Requisitos

• Node.js >= 20.0.0

• Servidor MCP ascendente con:

  • Transporte SSE o HTTP transmitible (para --upstream), O

  • Transporte stdio (para --upstream-stdio)

Licencia

MIT

Copyright (c) 2026 Respawn LLC