shutup-mcp

Experimental MCP tool-list filtering proxy for large tool catalogs.

shutup-mcp sits between an MCP client and one or more MCP servers. It aggregates tool definitions and exposes only the top-k tools that match the current intent.

This repository is an alpha implementation seed. It is useful for experimenting with tool-list compression, but it is not yet a full production MCP gateway.

What It Does

• Reads a Claude Desktop-style MCP config.
• Discovers configured MCP servers.
• Fetches and prefixes upstream tools.
• Builds a hybrid retrieval index over tool names and descriptions.
• Filters tools/list results using:
  • explicit CLI intent;
  • a runtime shutup__set_intent tool;
  • fallback behavior when no intent is known.
• Routes tools/call to the correct upstream server.
• Supports local embedding backends:
  • sentence-transformers;
  • ollama.

What It Does Not Yet Do

This alpha does not yet provide:

• full MCP request proxying for every capability;
• persistent upstream sessions for every server;
• guaranteed client-side dynamic intent detection across all MCP clients;
• production authentication or sandboxing;
• benchmark-backed token or latency claims.

Earlier README versions included strong reduction metrics. Those are removed until reproducible benchmarks are added.

Install

pip install shutup-mcp

For local development:

pip install -e ".[dev]"

CLI Usage

One-shot tool filtering

shutup \
  --config ~/Library/Application\ Support/Claude/claude_desktop_config.json \
  --intent "read and write local files" \
  --top-k 5

This prints a JSON array of filtered tool definitions.

Run as MCP proxy

shutup \
  --config ~/Library/Application\ Support/Claude/claude_desktop_config.json \
  --intent "work with GitHub issues" \
  --serve \
  --top-k 5

If --intent is supplied, tools/list returns only top-k tools matching that intent.

If no intent is supplied, the proxy exposes a small control tool:

shutup__set_intent

Calling this tool updates the current intent, after which tools/list can be filtered.

Claude Desktop Configuration

Example:

{
  "mcpServers": {
    "shutup": {
      "command": "shutup",
      "args": [
        "--config",
        "/absolute/path/to/claude_desktop_config.json",
        "--serve",
        "--intent",
        "work with GitHub issues",
        "--top-k",
        "5"
      ]
    }
  }
}

Example MCP Server Config

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Embedder Options

Command Options

shutup --config PATH [--intent TEXT] [--top-k K] [--embedder BACKEND] [--serve]

Runtime Intent Tool

The proxy exposes a control tool:

shutup__set_intent

Input:

{
  "intent": "create and triage GitHub issues"
}

Output:

{
  "ok": true,
  "intent": "create and triage GitHub issues"
}

This provides an explicit client-controlled intent update path.

Testing

pip install -e ".[dev]"
pytest -q

Tests use the lightweight fake embedder and do not download embedding models.

Security Notes

shutup-mcp reads and launches MCP servers from a config file. Treat that config file as executable configuration.

Do not use untrusted server configs.

This project filters tool visibility; it does not enforce policy, authorization, sandboxing, or data-loss prevention.

License

MIT