Tool Filtering

Tool Filtering

New in v2.6.4

Some MCP clients have tool limits (e.g., Windsurf's 100-tool limit). Use the SQLITE_MCP_TOOL_FILTER environment variable to expose only the tools you need, reducing token overhead and staying under client limits.

---

Overview

The SQLite MCP Server exposes 73 tools by default. While this provides comprehensive functionality, some MCP clients:

• Have hard limits on tool count (Windsurf: 100 tools)
• Become unstable with too many tools (Cursor: warnings at ~80, issues past ~120)
• Consume more tokens sending tool definitions

Tool filtering solves this by letting you selectively enable/disable tools at the server level.

---

Configuration

Set the SQLITE_MCP_TOOL_FILTER environment variable in your MCP client configuration.

Cursor / Windsurf (uvx)

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/neverinfamous/sqlite-mcp-server.git",
        "mcp-server-sqlite",
        "--db-path",
        "/path/to/your/database.db"
      ],
      "env": {
        "SQLITE_MCP_TOOL_FILTER": "-vector,-stats,-spatial,-text"
      }
    }
  }
}

Claude Desktop (Python)

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server_sqlite", "--db-path", "/path/to/database.db"],
      "env": {
        "SQLITE_MCP_TOOL_FILTER": "-vector,-stats,-spatial"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "sqlite": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SQLITE_MCP_TOOL_FILTER=-vector,-stats,-spatial,-text",
        "-v", "/path/to/project:/workspace",
        "writenotenow/sqlite-mcp-server:latest",
        "--db-path", "/workspace/database.db"
      ]
    }
  }
}

---

Filter Syntax

Syntax	Description	Example
-group	Disable all tools in a group	-vector disables 11 vector tools
-tool	Disable a specific tool	-write_query disables only write_query
+tool	Re-enable a tool after group disable	+vacuum_database re-enables vacuum

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

Examples

# Disable then enable = tool is ENABLED
SQLITE_MCP_TOOL_FILTER="-admin,+vacuum_database"
# Result: vacuum_database is enabled, other admin tools disabled

# Enable then disable = tool is DISABLED  
SQLITE_MCP_TOOL_FILTER="+vacuum_database,-admin"
# Result: vacuum_database is disabled (along with all admin tools)

---

Available Groups

Group	Tool Count	Tools
core	5	read_query, write_query, create_table, list_tables, describe_table
fts	4	fts_search, create_fts_table, rebuild_fts_index, hybrid_search
vector	11	semantic_search, semantic_query, setup_semantic_search, create_embeddings_table, store_embedding, create_vector_index, analyze_vector_index, rebuild_vector_index, optimize_vector_search, batch_similarity_search, calculate_similarity
json	9	json_query, json_select, json_insert, json_update, json_merge, json_validate_path, validate_json, analyze_json_schema, create_json_collection_table
virtual	8	create_csv_table, create_enhanced_csv_table, create_rtree_table, create_series_table, list_virtual_tables, drop_virtual_table, virtual_table_info, analyze_csv_schema
spatial	7	load_spatialite, create_spatial_table, spatial_query, spatial_analysis, spatial_index, geometry_operations, import_shapefile
text	7	fuzzy_match, phonetic_match, regex_extract, regex_replace, text_normalize, text_similarity, text_validation
stats	8	descriptive_statistics, correlation_analysis, distribution_analysis, hypothesis_testing, outlier_detection, percentile_analysis, moving_averages, regression_analysis
admin	14	vacuum_database, optimize_database, analyze_database, integrity_check, backup_database, restore_database, verify_backup, database_stats, index_usage_stats, pragma_compile_options, pragma_database_list, pragma_optimize, pragma_settings, pragma_table_info
misc	5	append_insight, summarize_table, hybrid_search_workflow, advanced_search, test_jsonb_conversion

Total: 73 tools across 10 groups

---

Common Configurations

Windsurf (Stay Under 100 Tools)

Disable heavy groups to reduce to ~50 tools:

SQLITE_MCP_TOOL_FILTER="-vector,-stats,-spatial,-text"

Read-Only Mode

Prevent any write operations:

SQLITE_MCP_TOOL_FILTER="-write_query,-create_table"

Core + JSON Only (Minimal Footprint)

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

SQLITE_MCP_TOOL_FILTER="-fts,-vector,-virtual,-spatial,-text,-stats,-admin,-misc"

Admin Tools with Specific Exceptions

Disable admin group but keep vacuum and backup:

SQLITE_MCP_TOOL_FILTER="-admin,+vacuum_database,+backup_database"

Analytics Focus

Keep stats and text processing, disable spatial/vector:

SQLITE_MCP_TOOL_FILTER="-vector,-spatial,-virtual"

---

Behavior Notes

1. No Filter = All Tools: If SQLITE_MCP_TOOL_FILTER is not set or empty, all 73 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 returns an error message: "Tool 'X' is disabled by filtering configuration"

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

Tool filtering significantly reduces context window consumption:

Configuration	Approx. Tools	Token Savings
No filtering	73	Baseline
-vector,-stats,-spatial,-text	~40	~45% reduction
Core + JSON only	~14	~80% reduction

This is particularly valuable for:

• Clients with strict token limits
• Faster tool discovery by AI
• Reduced API costs

---

See Also

• Quick Start - Getting started guide
• MCP Resources & Prompts - AI integration features
• Changelog - Version history