Tool Filtering — Enable & Disable Specific MCP Tools
Pick exactly which of the 10 tools your AI agent can see. Minimum 2, maximum 9. Save with one command, restart your editor.
Why filter tools?
By default Zephex exposes all 10 MCP tools to your agent. Some users want fewer:
- Less context noise — fewer tools in the agent's tool list = clearer reasoning
- Lower token use — the agent gets less "tool descriptions" in every message
- Specific workflows — only need code search? Just expose
find_codeandread_code - Compliance — internal policies that limit what an agent can call
How filtering works
┌─────────────────────────────────────────────────┐
│ Your editor │
│ (Cursor, Claude Code, VS Code, ...) │
└─────────────────┬───────────────────────────────┘
│ MCP request: tools/list
▼
┌─────────────────────────────────────────────────┐
│ Zephex CLI (local) │
│ Reads ~/.zephex/config.json │
│ ┌────────────────────────────────────────────┐ │
│ │ { │ │
│ │ "enabledTools": [ │ │
│ │ "find_code", │ │
│ │ "read_code", │ │
│ │ "check_test" │ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────┘ │
└─────────────────┬───────────────────────────────┘
│
▼ Filtered list (3 tools shown)
┌─────────────────────────────────────────────────┐
│ Agent sees only: │
│ ● find_code │
│ ● read_code │
│ ● check_test │
│ │
│ (other 7 tools never appear in tool list) │
└─────────────────────────────────────────────────┘The filter lives in ~/.zephex/config.json. The local Zephex CLI reads it and removes filtered-out tools from the response before forwarding to your editor.
Quick reference
# See all 10 tools and which are enablednpx zephex tools # Enable just 2 tools (the minimum)npx zephex tools --enable find_code,read_code # Enable 3 code toolsnpx zephex tools --enable find_code,read_code,check_test # Enable 5 — all the code-related toolsnpx zephex tools --enable find_code,read_code,check_test,get_project_context,explain_architecture # Re-enable all 10npx zephex tools --resetConstraints:
- Minimum: 2 tools. Fewer than 2 means the filter is rejected.
- Maximum: 9 tools. If you want all 10, use
--resetinstead of listing them — it removes the filter entirely. - Tool names are case-sensitive: use
find_codenotFind_Code.
The 10 tools
Code tools (5)
┌──────────────────────────────────────────────────────────────────┐ │ find_code BM25 search across the codebase │ │ read_code AST-based reader (symbol/file/outline) │ │ check_test Plain English task → focus files │ │ get_project_context Stack, scripts, env vars, monorepos │ │ explain_architecture Mermaid diagrams + dependency analysis │ └──────────────────────────────────────────────────────────────────┘
Reasoning tools (1)
┌──────────────────────────────────────────────────────────────────┐ │ keep_thinking Persistent reasoning state │ └──────────────────────────────────────────────────────────────────┘
Web tools (3)
┌──────────────────────────────────────────────────────────────────┐ │ audit_headers HTTP / TLS / cookie audit of any URL │ │ check_package Live npm / pypi / cargo safety check │ │ project_memory Remember and recall project decisions, gotchas, and │ └──────────────────────────────────────────────────────────────────┘
Knowledge tools (1)
┌──────────────────────────────────────────────────────────────────┐ │ Zephex_dev_info Expert dev knowledge base │ └──────────────────────────────────────────────────────────────────┘
Recipes by use case
Just code search and reading
Minimal setup — agent can search and read code, nothing else.
npx zephex tools --enable find_code,read_codeCode search + project understanding
Add project context so the agent knows the stack and scripts.
npx zephex tools --enable find_code,read_code,get_project_contextRefactoring helper
Adds check_test for "here's what I want to do" → focus files.
npx zephex tools --enable find_code,read_code,check_testRefactoring + reasoning
Adds keep_thinking so the agent can keep persistent reasoning state across long sessions.
npx zephex tools --enable find_code,read_code,check_test,keep_thinkingFull code intelligence
Every code tool plus reasoning. Drops only web/knowledge tools.
npx zephex tools --enable find_code,read_code,check_test,get_project_context,explain_architecture,keep_thinkingSecurity review only
Just the tools an agent needs to do a dependency / header audit.
npx zephex tools --enable check_package,project_memory,audit_headersArchitecture review only
Just the tools an agent needs to map a codebase.
npx zephex tools --enable get_project_context,explain_architecture,find_codeWeb work only
For an agent that audits / debugs deployed sites.
npx zephex tools --enable audit_headers,Zephex_dev_infoUpgrade-planning helper
For an agent that plans dependency upgrades.
npx zephex tools --enable check_package,project_memory,find_code,read_codeRe-enable everything
npx zephex tools --resetDecision flowchart
Do you want all 10 tools?
│
┌───────────┴───────────┐
│ │
YES NO
│ │
▼ ▼
npx zephex tools What's the agent doing?
--reset │
┌──────────┼──────────┬──────────┐
│ │ │ │
Reading Refactoring Security Web work
code only tasks review / docs
│ │ │ │
▼ ▼ ▼ ▼
find_code, find_code, check_package, audit_headers,
read_code read_code, project_memory, Zephex_dev_info
check_test, audit_headers
keep_thinkingWhat gets saved
The filter is stored in ~/.zephex/config.json (Mac/Linux) or %USERPROFILE%\\.zephex\\config.json (Windows):
{ "enabledTools": [ "find_code", "read_code", "check_test" ]}This file is read by the local Zephex CLI on every tools/list request from your editor. To remove the filter, either:
- Run
npx zephex tools --reset - Or delete the
enabledToolsfield manually - Or delete
~/.zephex/config.jsonentirely
Common errors
"You need to enable at least 2 tools"
Got: npx zephex tools --enable find_code
Fix: list at least 2 tool names, comma-separated:
npx zephex tools --enable find_code,read_code"You're trying to enable all 10 tools"
Got: npx zephex tools --enable find_code,read_code,check_test,... with all 10 listed.
Fix: use --reset instead — it removes the filter so every tool is enabled by default.
npx zephex tools --reset"Unknown tools: ..."
You misspelled a tool name. The valid names are case-sensitive:
find_code (not Find_Code, findCode, find-code)read_code (not Read_Code, readCode)check_test (not scope-task, scopeTask)get_project_context (not getProjectContext)explain_architecture (not Explain_Architecture)keep_thinking (not thinking, Thinking, think)audit_headers (not auditHeaders)check_package (not checkPackage)project_memory (not auditPackage)Zephex_dev_info (note the capital Z)Filter saved but tools still appear in editor
You need to fully restart your editor. Just reloading the window may not pick up the new tool list. Quit completely (Cmd+Q on Mac) and reopen.
Per-editor vs global filtering
The filter is currently global — it applies to every editor that uses the same Zephex CLI installation. Per-editor filtering (different tool sets in different editors) is on the roadmap.
Workaround: you can install Zephex globally for some editors and use --project install for others, then drop a .zephex/config.json in the project folder. The CLI will read the project-local config first.
Where to next
- CLI Commands — full reference for all 15 commands
- Tool Reference — what each tool does
- Setup Walkthrough — visual install diagram
- Best Practices — how to get the most from Zephex