@squadbase/mcp-bonsai

A middleware proxy for filtering tools, resources, and prompts from MCP (Model Context Protocol) servers.

Overview

mcp-bonsai sits between LLM clients (like Claude Code) and MCP servers as a proxy. It intercepts JSON-RPC messages and filters tools/list, resources/list, and prompts/list responses based on your configuration.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ LLM Client  │ ──► │ mcp-bonsai  │ ──► │ MCP Server  │
│ (Claude)    │ ◄── │  (Proxy)    │ ◄── │             │
└─────────────┘     └─────────────┘     └─────────────┘
                          │
                    Filters based on
                    configuration

Installation

npm install @squadbase/mcp-bonsai

Usage

CLI

npx mcp-bonsai --name <identifier> --command "<mcp-server-command>" [options]

Options

| Option | Required | Description | |--------|:--------:|-------------| | -n, --name <identifier> | ✅ | Identifier for config lookup | | -c, --command <cmd> | ✅ | MCP server command to spawn | | -f, --config <path> | | Config file path or JSON string | | --debug | | Enable debug logging to stderr |

Examples

# Filter next-devtools-mcp
npx mcp-bonsai \
  --name next-devtools \
  --command "npx -y next-devtools-mcp@latest" \
  --config ./mcp-bonsai.json

# Pass config as JSON string
npx mcp-bonsai \
  --name myserver \
  --command "uvx some-mcp-server" \
  --config '{"myserver": {"tools": ["allowed_tool"]}}'

Configuration

Configuration uses a whitelist approach to specify which tools, resources, and prompts are allowed.

Supported Formats

• JSON (.json)
• YAML (.yaml, .yml)

Schema

{
  "<server-name>": {
    "tools": ["tool1", "tool2"],
    "resources": ["resource://*"],
    "prompts": ["prompt1"]
  }
}

| Field | Type | Description | |-------|------|-------------| | tools | string[] | List of allowed tool names | | resources | string[] | List of allowed resource URIs (supports wildcards) | | prompts | string[] | List of allowed prompt names |

Configuration Examples

Filtering next-devtools-mcp

{
  "next-devtools": {
    "tools": [
      "init",
      "nextjs_docs",
      "nextjs_index",
      "nextjs_call"
    ],
    "resources": [],
    "prompts": []
  }
}

This configuration blocks browser_eval, enable_cache_components, and upgrade_nextjs_16.

YAML Format

next-devtools:
  tools:
    - init
    - nextjs_docs
    - nextjs_index
  resources: []
  prompts: []

Wildcards

Resource filtering supports wildcards (*).

{
  "myserver": {
    "resources": [
      "file://*",
      "system_logs://*"
    ]
  }
}

Usage with Claude Code

Register mcp-bonsai as an MCP server in ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "next-devtools-filtered": {
      "command": "npx",
      "args": [
        "mcp-bonsai",
        "--name", "next-devtools",
        "--command", "npx -y next-devtools-mcp@latest",
        "--config", "/path/to/mcp-bonsai.json"
      ]
    }
  }
}

How It Works

1. Startup: Spawns the specified MCP server as a child process
2. Passthrough: Most messages are forwarded as-is
3. Filtering: Only tools/list, resources/list, and prompts/list responses are filtered based on configuration
4. Execution: tools/call and other execution requests are passed through without modification

Debugging

Use the --debug option to output detailed logs to stderr:

npx mcp-bonsai \
  --name next-devtools \
  --command "npx -y next-devtools-mcp@latest" \
  --config ./mcp-bonsai.json \
  --debug

Debug logs show:

• Client requests received
• Server responses received
• Filtered tools/resources/prompts

Development

# Build
npm run build

# Type check
npm run typecheck

# Unit tests
npm test

# Integration tests (requires network)
npm run test:integration

# Development mode (watch)
npm run dev

License

MIT