Skip to content

Tool Filtering

Jump to bottom
Chris & Mike edited this page Apr 12, 2026 · 25 revisions

Tool Filtering

New in v2.2.0

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

Overview

The Memory Journal MCP Server exposes 70 tools by default. While this is modest compared to some servers, 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.

Important

All shortcuts and tool groups include Code Mode (mj_execute_code) by default for token-efficient operations. To exclude it, add -codemode to your filter. See Code Mode for details.

Configuration

Set the MEMORY_JOURNAL_MCP_TOOL_FILTER environment variable in your MCP client configuration.

Cursor / Windsurf (npm)

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "MEMORY_JOURNAL_MCP_TOOL_FILTER": "-admin,-backup"
      }
    }
  }
}

Claude Desktop (npm)

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "MEMORY_JOURNAL_MCP_TOOL_FILTER": "-admin"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MEMORY_JOURNAL_MCP_TOOL_FILTER=-admin,-backup",
        "-v",
        "./data:/app/data",
        "writenotenow/memory-journal-mcp:latest"
      ]
    }
  }
}

Or via shell:

docker run -i --rm \
  -e MEMORY_JOURNAL_MCP_TOOL_FILTER="-github,-analytics" \
  -v ./data:/app/data \
  writenotenow/memory-journal-mcp:latest

Filter Syntax

Syntax Description Example
shortcut Use a predefined bundle (whitelist) starter enables core + search + codemode
group Enable a specific group (whitelist) core,search enables only those groups
tool_name Enable a specific tool (whitelist) create_entry,search_entries enables only those tools
-group Disable all tools in a group -analytics disables 2 analytics tools
-tool Disable a specific tool -delete_entry disables only delete_entry
+tool Re-enable a tool after group disable +update_entry re-enables update

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

Examples

# Disable then enable = tool is ENABLED
MEMORY_JOURNAL_MCP_TOOL_FILTER="-admin,+update_entry"
# Result: update_entry is enabled, delete_entry is disabled

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

Custom Tool Selection

You can list individual tool names (without + prefix) to create a fully custom whitelist — only the tools you specify will be enabled:

# Enable exactly 3 tools (whitelist mode)
MEMORY_JOURNAL_MCP_TOOL_FILTER="create_entry,search_entries,semantic_search"

# Mix tools from different groups
MEMORY_JOURNAL_MCP_TOOL_FILTER="create_entry,get_github_issues,backup_journal"

# Combine with a shortcut and subtract
MEMORY_JOURNAL_MCP_TOOL_FILTER="starter,+export_entries"

This is useful for scripted or automated clients that need a minimal, precise set of capabilities.

Available Groups

Group Tool Count Tools
codemode 1 mj_execute_code 🌟 Recommended
core 6 create_entry, create_entry_minimal, get_recent_entries, get_entry_by_id, list_tags, test_simple
search 4 search_entries, search_by_date_range, semantic_search, get_vector_index_stats
analytics 2 get_statistics, get_cross_project_insights
relationships 2 link_entries, visualize_relationships
io 3 export_entries, export_markdown, import_markdown
admin 5 update_entry, delete_entry, rebuild_vector_index, add_to_vector_index, merge_tags
github 18 get_github_issues, get_github_prs, get_github_issue, get_github_pr, get_github_context, get_kanban_board, move_kanban_item, add_kanban_item, delete_kanban_item, create_github_issue_with_entry, close_github_issue_with_entry, get_github_milestones, get_github_milestone, create_github_milestone, update_github_milestone, delete_github_milestone, get_repo_insights, get_copilot_reviews
backup 4 backup_journal, list_backups, restore_backup, cleanup_backups
team 25 team_create_entry, team_get_recent, team_search, team_get_entry_by_id, team_list_tags, team_search_by_date_range, team_update_entry, team_delete_entry, team_merge_tags, team_get_statistics, team_link_entries, team_visualize_relationships, team_export_entries, team_export_markdown, team_import_markdown, team_backup, team_list_backups, team_semantic_search, team_get_vector_index_stats, team_rebuild_vector_index, team_add_to_vector_index, team_get_cross_project_insights, team_get_collaboration_matrix, pass_team_flag, resolve_team_flag

Total: 70 tools across 10 groups

Meta-Groups (Presets)

Meta-groups are shortcuts that expand to multiple tool groups at once. Use them as the first item in a whitelist-mode filter:

Meta-Group Expands To Tools
starter core, search, codemode 11
essential core, codemode 7
full core, search, analytics, relationships, io, admin, github, backup, team, codemode 70
readonly core, search, analytics, relationships, io, codemode 18
codemode codemode 1

Usage

Meta-groups enable whitelist mode — only the specified groups are active:

# Start with starter preset (core + search + codemode = 11 tools)
MEMORY_JOURNAL_MCP_TOOL_FILTER="starter"

# Starter minus a specific tool
MEMORY_JOURNAL_MCP_TOOL_FILTER="starter,-get_vector_index_stats"

# Read-only mode (no mutations)
MEMORY_JOURNAL_MCP_TOOL_FILTER="readonly"

# Full preset minus admin (same as -admin in blacklist mode)
MEMORY_JOURNAL_MCP_TOOL_FILTER="full,-admin"

Note: Meta-groups without a +/- prefix activate whitelist mode. Subsequent -tool or -group rules subtract from the preset. This differs from blacklist mode (starting with -), which begins with all 70 tools enabled.

Common Configurations

Production Use (Disable Admin Tools)

Disable destructive admin tools in production:

MEMORY_JOURNAL_MCP_TOOL_FILTER="-admin"

This reduces from 70 to 65 tools.

No Admin Mode

Prevent modifications to existing entries (update, delete, merge tags, vector index management):

MEMORY_JOURNAL_MCP_TOOL_FILTER="-admin"

Users can still create new entries and link entries but cannot update or delete existing ones.

Tip

For true read-only access (no creates, no mutations), use the readonly preset: MEMORY_JOURNAL_MCP_TOOL_FILTER="readonly" (~16 tools).

Core Only (Minimal Footprint)

Only keep essential CRUD operations (6 tools):

MEMORY_JOURNAL_MCP_TOOL_FILTER="-search,-analytics,-relationships,-io,-admin,-github,-backup,-team"

Lightweight Mode

Keep core and search, disable everything else (10 tools):

MEMORY_JOURNAL_MCP_TOOL_FILTER="-analytics,-relationships,-io,-admin,-github,-backup,-team"

Admin Tools with Specific Exceptions

Disable admin group but keep update_entry:

MEMORY_JOURNAL_MCP_TOOL_FILTER="-admin,+update_entry"

Analytics Focus

Keep analytics and relationships, disable admin and backup:

MEMORY_JOURNAL_MCP_TOOL_FILTER="-admin,-backup"

Behavior Notes

  1. No Filter = All Tools: If MEMORY_JOURNAL_MCP_TOOL_FILTER is not set or empty, all 70 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 clarity
Claude Desktop ✅ Works Full compatibility
Windsurf ✅ Works Useful 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 reduces context window consumption by removing tool schema definitions from each request. Each tool definition consumes tokens for its name, description, and parameter schema.

Token Savings by Configuration

Configuration Filter Tools Est. Token Savings
Full (default) (none) 70 Baseline (~8,500 tokens)
No Admin -admin 65 ~9% (~750 tokens/request)
No GitHub -github 52 ~29% (~2,450 tokens/request)
Focused -admin,-github 47 ~38% (~3,250 tokens/request)
Minimal Search -analytics,-relationships,-io,-admin,-github,-backup,-team 11 ~75% (~6,400 tokens/request)
Core Only -search,-analytics,-relationships,-io,-admin,-github,-backup,-team 7 ~84% (~7,100 tokens/request)

Real-World Impact

Per-conversation savings depend on how many tool calls are made:

  • Each AI request includes tool schemas in the context
  • Fewer tools = smaller context = more room for actual content
  • At typical API pricing (~$0.002/1K tokens), lightweight mode saves ~$0.003/request

Why This Matters

  1. MCP Client Limits - Windsurf has a 100-tool limit; Cursor warns at ~80 tools
  2. Faster AI Responses - Smaller context = faster processing
  3. Reduced API Costs - Fewer tokens = lower bills
  4. Cleaner Tool Lists - AI can focus on relevant tools
  5. Better Tool Selection - AI makes better choices with fewer options

Use Cases

1. Production Deployment

MEMORY_JOURNAL_MCP_TOOL_FILTER="-admin"

Disable destructive admin tools (update, delete) in production environments.

2. Team Collaboration

MEMORY_JOURNAL_MCP_TOOL_FILTER="-admin"

Allow team members to create entries but not modify or delete others' work.

3. CI/CD Pipeline

MEMORY_JOURNAL_MCP_TOOL_FILTER="-admin,-backup"

Automated systems only need core operations, search, and analytics.

4. Lightweight Desktop Client

MEMORY_JOURNAL_MCP_TOOL_FILTER="-search,-analytics,-relationships,-io,-admin,-github,-backup,-team"

Minimal tool set for basic journaling without advanced features.

5. Power User Workflow

No filtering - use all 70 tools for maximum capability.

Troubleshooting

Filter Not Working

  1. Check environment variable name: Must be exactly MEMORY_JOURNAL_MCP_TOOL_FILTER
  2. Restart server: Filter is cached at startup
  3. Check syntax: Rules must start with - or +
  4. Check logs: Look for filter warnings in stderr

Tool Still Appears

  1. Check spelling: Tool and group names are case-sensitive
  2. Check order: Enable (+) after disable (-) = enabled
  3. Clear cache: Restart the MCP server

All Tools Disabled

If you accidentally disable everything:

# Remove the filter temporarily
unset MEMORY_JOURNAL_MCP_TOOL_FILTER

Then restart the server.

See Also

Examples in Context

Example 1: Cursor Configuration

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "MEMORY_JOURNAL_MCP_TOOL_FILTER": "-admin",
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Example 2: Docker Compose

version: "3.8"
services:
  memory-journal:
    image: writenotenow/memory-journal-mcp:latest
    volumes:
      - ./data:/app/data
    environment:
      - MEMORY_JOURNAL_MCP_TOOL_FILTER=-admin,-backup
      - GITHUB_TOKEN=${GITHUB_TOKEN}
    stdin_open: true
    tty: true

Example 3: Shell Script

#!/bin/bash
export MEMORY_JOURNAL_MCP_TOOL_FILTER="-admin,-backup"
export GITHUB_TOKEN="your_token"

docker run -i --rm \
  -e MEMORY_JOURNAL_MCP_TOOL_FILTER \
  -e GITHUB_TOKEN \
  -v ./data:/app/data \
  writenotenow/memory-journal-mcp:latest

Need help? Open an issue on GitHub.

🏠 Home

Getting Started

Core Features

Knowledge Graph

GitHub Integration

Workflows

Deployment

Architecture

Clone this wiki locally