subagent-mcp

An MCP server that acts as a context firewall between your coding agent and the open web. Instead of the agent burning tokens searching for docs and version info itself, it fires off a natural-language query and gets back a distilled answer.

Tools

resolve_package_versions — given a list of packages, returns the most recent mutually-compatible versions. Fetches live data directly from PyPI and npm registries, then runs a Claude Haiku subagent to reason about compatibility.

lookup_docs — given a library name and a natural-language question, returns an answer distilled from the official docs. Runs a Claude Sonnet subagent with web_search enabled; the search traffic never touches your main agent's context.

Why this exists

Doc-lookup MCP servers typically return raw search results or raw doc chunks. Your agent then has to read through them, which burns context that could be used on actual work. This server flips that: the agent sends a question, an LLM subagent with its own fresh context does the hunting, and only the answer comes back.

Running

Requires Docker and an Anthropic API key.

Set your ANTHROPIC_API_KEY in a .env inside of the /subagent-mcp folder

cd subagent-mcp
make run

To stop:

make down

To tail logs:

make logs

To wipe the Redis cache volume entirely:

make clean

Connecting to the Server

{
  "mcpServers": {
    "subagent-mcp": {
      "url": "http://localhost:8765/mcp"
    }
  }
}

Then reload MCP servers. The server must be running (make run) before your agent can connect.

Priming the agent

After connecting, paste this into your first message to make the agent aware of what's available and when to use it:

I have a local MCP server running called subagent-mcp. It exposes four tools — use them instead of searching yourself or guessing from training data:

- resolve_package_versions — fetches live PyPI/npm registry data and returns the latest mutually-compatible versions. Use this every time you write a dependency file.
- lookup_docs — searches official documentation and returns a distilled answer. Use this before writing non-trivial integration code for any library.
- search_examples — finds real working code examples from official repos and GitHub. Use this when you need to see how something is actually done.
- explain_error — diagnoses an error message and returns a concrete fix. Use this before guessing at a cause.

Do not run your own web searches for anything these tools cover.

Configuration

All settings are controlled via environment variables. Set them in your shell before make run, or place them in a subagent-mcp/.env file (picked up automatically by Docker Compose).

Variable	Default	Description
ANTHROPIC_API_KEY	—	Required. Anthropic API key.
SUBAGENT_MCP_VERSION_MODEL	claude-haiku-4-5-20251001	Model used for version resolution.
SUBAGENT_MCP_DOCS_MODEL	claude-sonnet-4-6	Model used for doc lookup.
SUBAGENT_MCP_MAX_SEARCH_USES	5	Max web searches the docs subagent can make per call.
SUBAGENT_MCP_SUBAGENT_TIMEOUT_SECONDS	60	Hard timeout for any subagent call.
SUBAGENT_MCP_REGISTRY_TIMEOUT_SECONDS	15	HTTP timeout for PyPI/npm registry fetches.
SUBAGENT_MCP_PORT	8765	Port the server listens on.
SUBAGENT_MCP_LOG_LEVEL	INFO	Log level (DEBUG, INFO, WARNING, ERROR).
SUBAGENT_MCP_CACHE_ENABLED	true*	Enable Redis result caching.
REDIS_URL	redis://cache:6379/0	Redis connection URL.
SUBAGENT_MCP_CACHE_REGISTRY_TTL_SECONDS	900	TTL for cached registry data (15 min).
SUBAGENT_MCP_CACHE_DOCS_TTL_SECONDS	345600	TTL for cached doc answers (96 hr).

* SUBAGENT_MCP_CACHE_ENABLED defaults to true in Docker Compose via the docker-compose.yaml environment block.

Lockfile

To regenerate uv.lock (e.g. after updating pyproject.toml):

make lock

This builds only the lockfile Docker stage and writes uv.lock back into the repo.