Skip to content

Tool Filtering

Jump to bottom
Temp edited this page Dec 8, 2025 · 1 revision

Tool Filtering

Optimize your PostgreSQL MCP Server for any client - Control tool count, reduce token usage, and improve performance.

New in v1.2.0

🎯 Why Tool Filtering?

The PostgreSQL MCP Server exposes 63 specialized tools by default, providing comprehensive PostgreSQL functionality. However, not every use case requires all tools. Tool filtering lets you:

Benefits

  • ✅ Stay Under Client Limits - Windsurf has a 100-tool limit, Cursor shows warnings at ~80 tools
  • ✅ Reduce Token Consumption - Save 24-86% on tool schema overhead (up to 10,800 tokens per conversation)
  • ✅ Remove Unused Tools - Disable tools requiring PostgreSQL extensions you haven't installed (pgvector, PostGIS)
  • ✅ Faster AI Tool Discovery - Smaller tool sets mean AI selects the right tool faster
  • ✅ Customize by Use Case - Different tool sets for development, production, analytics, CI/CD
  • ✅ Zero Breaking Changes - All tools enabled by default, completely backward compatible

Token Savings

Configuration Tools Exposed Tokens Saved Savings %
No filtering (default) 63 0 0%
-vector,-geo,-stats,-text 35 ~5,600 44%
-vector,-geo 48 ~3,000 24%
Core + JSON only 20 ~8,600 68%
Core only 9 ~10,800 86%

Based on ~200 tokens per tool definition (name, description, parameters, examples)

Real-World Impact

For a conversation with 10 AI exchanges:

  • Standard (63 tools): ~126,000 tokens in tool definitions
  • Filtered (35 tools): ~70,000 tokens in tool definitions
  • Savings: 56,000 tokens (~$1.68 at GPT-4 pricing)

Overview

Tool filtering solves common challenges:

MCP Client Challenges:

  • Windsurf: Hard limit of 100 tools
  • Cursor: Performance warnings at ~80 tools, instability past ~120
  • All clients: Higher token consumption with more tools

Use Case Challenges:

  • Development without pgvector/PostGIS extensions installed
  • Production read-only requirements
  • CI/CD pipelines needing only core operations
  • Analytics focus without spatial/vector operations

Solution: Use POSTGRES_MCP_TOOL_FILTER environment variable to selectively enable/disable tools at the server level.

Configuration

Set the POSTGRES_MCP_TOOL_FILTER environment variable in your MCP client configuration.

Cursor / Windsurf (Docker)

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URI",
        "-e", "POSTGRES_MCP_TOOL_FILTER",
        "writenotenow/postgres-mcp-enhanced:latest",
        "--access-mode=restricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://user:pass@localhost:5432/db",
        "POSTGRES_MCP_TOOL_FILTER": "-vector,-geo,-stats,-text"
      }
    }
  }
}

Claude Desktop (Python)

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "postgres-mcp",
      "args": ["--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "postgresql://user:pass@localhost:5432/db",
        "POSTGRES_MCP_TOOL_FILTER": "-vector,-geo,-stats,-text"
      }
    }
  }
}

Docker CLI

docker run -i --rm \
  -e DATABASE_URI="postgresql://user:pass@localhost:5432/db" \
  -e POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-stats,-text" \
  writenotenow/postgres-mcp-enhanced:latest \
  --access-mode=restricted

Filter Syntax

Syntax Description Example
-group Disable all tools in a group -vector disables 8 vector tools
-tool Disable a specific tool -execute_sql disables only execute_sql
+tool Re-enable a tool after group disable +list_schemas re-enables list_schemas

Rules are processed left-to-right, so order matters.

Examples

# Disable then enable = tool is ENABLED
POSTGRES_MCP_TOOL_FILTER="-core,+list_schemas"
# Result: list_schemas is enabled, other core tools disabled

# Enable then disable = tool is DISABLED  
POSTGRES_MCP_TOOL_FILTER="+list_schemas,-core"
# Result: list_schemas is disabled (along with all core tools)

Available Groups

Group Tool Count Tools
core 9 list_schemas, list_objects, get_object_details, explain_query, execute_sql, analyze_workload_indexes, analyze_query_indexes, analyze_db_health, get_top_queries
json 11 json_insert, json_update, json_select, json_query, json_validate_path, json_merge, json_normalize, json_diff, jsonb_index_suggest, json_security_scan, jsonb_stats
text 5 text_similarity, text_search_advanced, regex_extract_all, fuzzy_match, text_sentiment
stats 8 stats_descriptive, stats_percentiles, stats_correlation, stats_regression, stats_time_series, stats_distribution, stats_hypothesis, stats_sampling
performance 6 query_plan_compare, performance_baseline, slow_query_analyzer, connection_pool_optimize, vacuum_strategy_recommend, partition_strategy_suggest
vector 8 vector_embed, vector_similarity, vector_search, vector_cluster, vector_index_optimize, vector_dimension_reduce, hybrid_search, vector_performance
geo 7 geo_distance, geo_within, geo_buffer, geo_intersection, geo_index_optimize, geo_transform, geo_cluster
backup 4 backup_logical, backup_physical, restore_validate, backup_schedule_optimize
monitoring 5 monitor_real_time, alert_threshold_set, capacity_planning, resource_usage_analyze, replication_monitor

Total: 63 tools across 9 groups

Common Configurations

Windsurf (Stay Under 100 Tools)

Disable heavy groups to reduce to ~35 tools:

POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-stats,-text"

No Extensions Mode

Disable tools that require PostgreSQL extensions (pgvector, PostGIS):

POSTGRES_MCP_TOOL_FILTER="-vector,-geo"

Read-Only Mode

Prevent any write operations:

POSTGRES_MCP_TOOL_FILTER="-execute_sql"

Core + JSON Only (Minimal Footprint)

Only keep essential CRUD and JSON tools (~20 tools):

POSTGRES_MCP_TOOL_FILTER="-text,-stats,-performance,-vector,-geo,-backup,-monitoring"

Core Only (Ultra Minimal)

Only keep core database tools (~9 tools):

POSTGRES_MCP_TOOL_FILTER="-json,-text,-stats,-performance,-vector,-geo,-backup,-monitoring"

Core Tools with Specific Exceptions

Disable core group but keep list_schemas and explain_query:

POSTGRES_MCP_TOOL_FILTER="-core,+list_schemas,+explain_query"

Analytics Focus

Keep stats and performance, disable spatial/vector:

POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-backup"

CI/CD Mode

Disable backup and monitoring for automated pipelines:

POSTGRES_MCP_TOOL_FILTER="-backup,-monitoring"

Behavior Notes

  1. No Filter = All Tools: If POSTGRES_MCP_TOOL_FILTER is not set or empty, all 63 tools are enabled (backward compatible).

  2. Unknown Names Ignored: Invalid group or tool names are logged as warnings but don't cause errors.

  3. Disabled Tool Calls: If a disabled tool is called directly, it won't be available in the tool list.

  4. Caching: Filter configuration is cached at startup. Restart the server to apply changes.

Client Compatibility

Tool filtering works with all MCP-compliant clients:

Client Status Notes
Cursor ✅ Works Recommended for >80 tools
Claude Desktop ✅ Works Full compatibility
Windsurf ✅ Works Required for 100-tool limit
Other MCP Clients ✅ Works Standard MCP protocol

The filtering happens server-side, so no client-specific code is needed.

💰 Token Efficiency & Cost Savings

Tool filtering significantly reduces context window consumption and API costs:

Token Consumption

Configuration Tools Tool Def. Tokens Per-Exchange Overhead 10-Exchange Cost*
No filtering 63 ~12,600 12,600 tokens $3.78
-vector,-geo,-stats,-text 35 ~7,000 7,000 tokens $2.10
-vector,-geo 48 ~9,600 9,600 tokens $2.88
Core + JSON only 20 ~4,000 4,000 tokens $1.20
Core only 9 ~1,800 1,800 tokens $0.54

*Assumes GPT-4 pricing at ~$0.03/1K tokens

Cost Savings

Per Conversation (10 exchanges):

  • Windsurf config (-vector,-geo,-stats,-text): Save $1.68 (44% reduction)
  • No extensions (-vector,-geo): Save $0.90 (24% reduction)
  • Core only: Save $3.24 (86% reduction)

Per 1,000 Conversations:

  • Windsurf config: Save $1,680
  • No extensions: Save $900
  • Core only: Save $3,240

Performance Benefits

Beyond cost savings, tool filtering provides:

  • ⚡ Faster tool discovery - AI scans fewer tools to find the right one
  • 🎯 Better tool selection - Reduced noise from irrelevant tools
  • 📊 Lower latency - Smaller tool definitions mean faster API responses
  • 💾 Reduced context consumption - More room for actual conversation and data

Extension-Based Filtering

Many PostgreSQL MCP Server tools require optional PostgreSQL extensions:

Group Required Extension Installation
vector pgvector CREATE EXTENSION vector;
geo PostGIS CREATE EXTENSION postgis;

If you don't have these extensions installed, consider disabling these groups:

POSTGRES_MCP_TOOL_FILTER="-vector,-geo"

This reduces the tool count from 63 to 48 and prevents errors from tools that require missing extensions.

🎓 Best Practices

Development Environments

# Keep all tools except those requiring missing extensions
POSTGRES_MCP_TOOL_FILTER="-vector,-geo"  # If you don't have pgvector/PostGIS

Why: Maximum flexibility while avoiding errors from missing extensions.

Production Environments

# Windsurf: Stay under 100-tool limit
POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-stats,-text"

# Cursor: Stay under 80-tool warning threshold
POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-stats"

Why: Optimal balance of functionality and client stability.

CI/CD Pipelines

# Core operations only
POSTGRES_MCP_TOOL_FILTER="-backup,-monitoring"

Why: Automated tests typically only need core CRUD and query operations.

Analytics & Data Science

# Keep stats/performance, remove spatial/backup
POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-backup,-monitoring"

Why: Focus on statistical analysis and performance optimization.

Cost-Conscious Deployments

# Minimize token usage
POSTGRES_MCP_TOOL_FILTER="-json,-text,-stats,-performance,-vector,-geo,-backup,-monitoring"

Why: When every token counts, use only core database operations.

🔍 Validation & Debugging

Verify Active Tools

After starting the server with filtering, you can verify which tools are active:

  1. Check the server logs on startup
  2. Use database://capabilities resource to see active tool count
  3. List available tools in your MCP client

Troubleshooting

Issue: Tool still appears after disabling

  • Cause: Filter rules process left-to-right
  • Solution: Check rule order (e.g., +tool,-group enables tool, then disables it)

Issue: Too many tools still showing

  • Cause: Filter not set in environment
  • Solution: Verify POSTGRES_MCP_TOOL_FILTER is in your MCP client config env section

Issue: Tool not found error

  • Cause: Disabled a tool your workflow depends on
  • Solution: Re-enable with +tool or remove from filter

🚀 Quick Reference

Most Common Filters

# Windsurf (100-tool limit)
POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-stats,-text"

# No pgvector/PostGIS
POSTGRES_MCP_TOOL_FILTER="-vector,-geo"

# Core database only
POSTGRES_MCP_TOOL_FILTER="-json,-text,-stats,-performance,-vector,-geo,-backup,-monitoring"

# Read-only mode
POSTGRES_MCP_TOOL_FILTER="-execute_sql"

# Analytics focus
POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-backup"

Tool Group Reference

Group Count Tools Included
core 9 list_schemas, list_objects, get_object_details, explain_query, execute_sql, analyze_workload_indexes, analyze_query_indexes, analyze_db_health, get_top_queries
json 11 json_insert, json_update, json_select, json_query, json_validate_path, json_merge, json_normalize, json_diff, jsonb_index_suggest, json_security_scan, jsonb_stats
text 5 text_similarity, text_search_advanced, regex_extract_all, fuzzy_match, text_sentiment
stats 8 stats_descriptive, stats_percentiles, stats_correlation, stats_regression, stats_time_series, stats_distribution, stats_hypothesis, stats_sampling
performance 6 query_plan_compare, performance_baseline, slow_query_analyzer, connection_pool_optimize, vacuum_strategy_recommend, partition_strategy_suggest
vector 8 vector_embed, vector_similarity, vector_search, vector_cluster, vector_index_optimize, vector_dimension_reduce, hybrid_search, vector_performance
geo 7 geo_distance, geo_within, geo_buffer, geo_intersection, geo_index_optimize, geo_transform, geo_cluster
backup 4 backup_logical, backup_physical, restore_validate, backup_schedule_optimize
monitoring 5 monitor_real_time, alert_threshold_set, capacity_planning, resource_usage_analyze, replication_monitor

See Also

Clone this wiki locally