Skip to content
Back to search

lazy-mcp

MCP proxy server with lazy loading support - reduces context usage through on-demand tool activation

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/voicetreelab--lazy-mcp/badge.svg)](/listings/voicetreelab--lazy-mcp)

HTML

<a href="/listings/voicetreelab--lazy-mcp"><img src="/api/listings/voicetreelab--lazy-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

make build
./build/structure_generator --config config.json --output testdata/mcp_hierarchy

This generates the hierarchical structure in the output folder config.json specifies, by fetching the available tools from the mcp servers specified.

**Add to Claude Code:**

 claude mcp add --transport stdio mcp-proxy build/mcp-proxy -- --config config.json

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 184 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Lazy MCP
  2. Lazy MCP lets your agent fetch MCP tools only on demand, saving those tokens from polluting your context window.
  3. In [this](https://voicetree.io/blog/lazy-mcp+for+tool+instructions+only+on+demand) example, it saved 17% (34,000 tokens) of an entire claude code context window by hiding 2 MCP tools that aren't always needed.
  4. Welcoming open source contributions!
  5. ## How it Works
  6. Lazy MCP exposes two meta tools, which allows agents to explore a tree structure of available MCP tools and categories.
  7. - `get_tools_in_category(path)` - Navigate the tool hierarchy
  8. - `execute_tool(tool_path, arguments)` - Execute tools by path
  9. ## Example Flow
  10. ```
  11. 1. get_tools_in_category("") → {
  12. "categories": {
  13. "coding_tools": "Development tools... use when...",
  14. "web_tools": "description ... instructions"
  15. }
  16. }
  17. 2. get_tools_in_category("coding_tools") → {
  18. "categories": {
  19. "serena": "description ... instructions",
  20. }
  21. }
  22. 3. get_tools_in_category("coding_tools.serena") → {
  23. "tools": {"find_symbol": "...", "get_symbols_overview": "..."}
  24. }
  25. 4. execute_tool("coding_tools.serena.find_symbol", {...})
  26. → Lazy loads Serena server (if not already loaded)
  27. → Proxies request to Serena
  28. → Returns result
  29. ```
  30. ![img_1.png](img_1.png)
  31. ![img_2.png](img_2.png)
  32. ## Quick Start
  33. ```bash
  34. make build
  35. ```
  36. ```bash
  37. ./build/structure_generator --config config.json --output testdata/mcp_hierarchy
  38. ```
  39. This generates the hierarchical structure in the output folder config.json specifies, by fetching the available tools from the mcp servers specified.
  40. **Add to Claude Code:**
  41. ```bash
  42. claude mcp add --transport stdio mcp-proxy build/mcp-proxy -- --config config.json
  43. ```
  44. ## Configuration
  45. ### Basic Config Structure
  46. see [config.json](config.json) for an example.
  47. ### Tool Hierarchy Structure
  48. Tool hierarchy is defined in `testdata/mcp_hierarchy/` with JSON files:
  49. **Root node** (`testdata/mcp_hierarchy/root.json`):
  50. **Category nodes** (e.g., `testdata/mcp_hierarchy/github/github.json`):
  51. **Tool nodes** (e.g., `testdata/mcp_hierarchy/github/create_issue/create_issue.json`):
  52. ## Command Line Options
  53. ```bash
  54. ./mcp-proxy --help
  55. ```
  56. ## Permission Control with Claude Code Hooks
  57. When using lazy-mcp with Claude Code, all tool calls go through `execute_tool`. This means traditional MCP permission rules (like `mcp__github__create_issue`) don't apply directly.
  58. To control which tools require permission prompts, use **Claude Code hooks**.
  59. ### Option 1: Claude Code Native Hook (Recommended for Claude Code)
  60. Claude Code's `PreToolUse` hooks can inspect the `tool_path` argument and decide permission by outputting JSON:
  61. - **Allow:** Exit 0 (no output)
  62. - **Ask:** Exit 0 with `{"hookSpecificOutput": {"permissionDecision": "ask", ...}}`
  63. - **Deny:** Exit 0 with `{"hookSpecificOutput": {"permissionDecision": "deny", ...}}`
  64. #### Setup
  65. 1. **Copy the example hook script:**
  66. ```bash
  67. cp examples/hooks/check-sensitive-tools.sh ~/.claude/hooks/
  68. chmod +x ~/.claude/hooks/check-sensitive-tools.sh
  69. ```
  70. 2. **Configure Claude Code hooks** (in `~/.claude/settings.json` or project `.claude/settings.local.json`):
  71. ```json
  72. {
  73. "hooks": {
  74. "PreToolUse": [
  75. {
  76. "matcher": "mcp__lazy-mcp__execute_tool",
  77. "hooks": [
  78. {
  79. "type": "command",
  80. "command": "~/.claude/hooks/check-sensitive-tools.sh"
  81. }
  82. ]
  83. }
  84. ]
  85. }
  86. }
  87. ```
  88. 3. **Customize sensitive tools** via environment variables:
  89. ```bash
  90. # Tools that require permission prompts
  91. export LAZY_MCP_SENSITIVE_TOOLS="gmail.send_email,github.create_*,gitlab.create_*"
  92. # Tools that are completely blocked
  93. export LAZY_MCP_DENIED_TOOLS="*.force_delete_*"
  94. ```
  95. ### Option 2: Token-Based Hook (Recommended for OpenCode / General Use)
  96. Since not all agents support the `permissionDecision` JSON protocol, `lazy-mcp` also supports a universal "Token Hook" mechanism. This forces the agent to retry the operation after user confirmation.
  97. #### How It Works
  98. 1. **First Call:** Hook checks for a token. If missing, it exits with error `CONFIRMATION_NEEDED` and the path to the required token.
  99. 2. **Agent Response:** The agent catches this error, asks the user for confirmation, and creates the token file.
  100. 3. **Retry:** The agent retries the tool call. The hook finds the token, deletes it (one-time use), and allows execution.
  101. #### Setup
  102. 1. **Copy the token hook script:**
  103. ```bash
  104. cp examples/hooks/confirm-tool-token.sh /path/to/hooks/
  105. chmod +x /path/to/hooks/confirm-tool-token.sh
  106. ```
  107. 2. **Configure your agent** to call this script *before* `execute_tool`.
  108. ### Option 3: OpenCode Plugin
  109. For OpenCode users, a TypeScript plugin is available that logs warnings for sensitive actions.
  110. ```bash
  111. cp examples/plugins/opencode-sensitive-tools.ts .opencode/plugin/sensitive-tools-check.ts
  112. ```
  113. ### Default Sensitive Tools
  114. The example scripts include sensible defaults for public-facing actions:
  115. | Server | Sensitive Tools |
  116. |--------|-----------------|
  117. | Gmail | `send_email`, `create_draft`, `delete_email`, `trash_email` |
  118. | GitHub | `create_issue`, `create_pull_request`, `create_repository`, `push_files`, `create_or_update_file`, `create_branch`, `fork_repository` |
  119. | GitLab | `create_issue`, `create_merge_request`, `accept_merge_request`, `create_project`, `create_branch`, `create_or_update_file` |
  120. ### Pattern Syntax
  121. - **Exact match:** `gmail.send_email`
  122. - **Server prefix:** `gmail.*` (all gmail tools)
  123. - **Suffix match:** `*.delete_*` (all delete operations)
  124. ## Credits
  125. Forked from [TBXark/mcp-proxy](https://github.com/voicetreelab/lazy-mcp) - extended with hierarchical routing, lazy loading, and stdio support.
  126. ## License
  127. MIT License - see [LICENSE](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.