sidecar-mcp

An MCP server that delegates bulk file reading to a cheap worker LLM, so the main agent's context stays small.

When the main agent needs to understand 2+ files or any file over ~100 lines, it calls bulk_read. The full file content never enters the main agent's context — only the worker's summary does.

Install

sidecar-mcp is a small stdio subprocess that sits next to your coding agent. Reads happen out-of-band to a cheap worker LLM, so the main agent's context stays small. Two install paths — both wired in under a minute.

Any MCP client (canonical)

The MCP primitive is the same everywhere — a subprocess with a command and some env vars. Every client wraps it in its own config syntax. Pick your worker backend, set SIDECAR_BACKEND (and any keys), then plug this into your client's MCP config:

{
  "command": "npx -y @aemrezorlu/sidecar-mcp",
  "env": { "SIDECAR_BACKEND": "ollama" }
}

For a from-source install, swap npx -y @aemrezorlu/sidecar-mcp for node /absolute/path/to/sidecar-mcp/dist/index.js. See Wire into any MCP client below for client-specific config locations.

A. Claude Code CLI (once the package is on the npm registry)

If you're on Claude Code, claude mcp add is the shortest path — it writes the same config for you. The SIDECAR_BACKEND=* env vars are independent of the client; claude here is just the CLI that registers the MCP server.

# Ollama — local, free, no API key:
claude mcp add sidecar -e SIDECAR_BACKEND=ollama -- npx -y @aemrezorlu/sidecar-mcp

# OpenAI:
claude mcp add sidecar -e SIDECAR_BACKEND=openai -e SIDECAR_OPENAI_KEY="$OPENAI_API_KEY" -- npx -y @aemrezorlu/sidecar-mcp

# Anthropic (or any Anthropic-compatible provider):
claude mcp add sidecar -e SIDECAR_BACKEND=anthropic -e SIDECAR_ANTHROPIC_KEY="$ANTHROPIC_API_KEY" -- npx -y @aemrezorlu/sidecar-mcp
# Add -e SIDECAR_ANTHROPIC_URL=https://your-host for Anthropic-compatible proxies.

npx -y @aemrezorlu/sidecar-mcp downloads and runs the published package on first call. No clone, no build, no node_modules to manage.

B. From source (works today, no publish needed)

git clone https://github.com/dEMonaRE/sidecar-mcp.git
cd sidecar-mcp
pnpm install --frozen-lockfile
pnpm build
claude mcp add sidecar -e SIDECAR_BACKEND=ollama -- node "$PWD/dist/index.js"

Pick a backend

Verify

In your MCP client (Claude Code shown), ask: "Use bulk_read to summarize README.md." You should see bulk_read fire and return a tight summary. Every reply ends with a usage footer (tokens: <prompt> in / <completion> out):

---
sidecar: model=llama3.1:8b, backend=ollama, tokens=412 in / 87 out

If bulk_read doesn't show up:

• Claude Code: claude mcp list should show sidecar as connected.

• VS Code Copilot: Command Palette → "MCP: List Servers".

• Codex CLI: codex mcp list.

• Cursor / Zed: check the MCP panel in settings.

Related MCP server: Ultra-Eye

Configuration

sidecar-mcp reads everything from env vars. No config file. No CLI flags (MCP stdio can't pass them).

Default models:

• ollama → llama3.1:8b

• openai → gpt-4o-mini

• anthropic → claude-3-5-haiku-latest

Per-backend quick config

Ollama (local, free, no API key)

ollama serve &
ollama pull llama3.1:8b
export SIDECAR_BACKEND=ollama

OpenAI

export SIDECAR_BACKEND=openai
export SIDECAR_OPENAI_KEY=sk-...

Anthropic (or any Anthropic-compatible provider)

export SIDECAR_BACKEND=anthropic
export SIDECAR_ANTHROPIC_KEY=sk-ant-...
# Optional — point at a proxy that speaks the Anthropic Messages API:
# export SIDECAR_ANTHROPIC_URL=https://your-anthropic-compatible-host

Wire into any MCP client

The MCP spec is the same everywhere — sidecar-mcp is a subprocess with a command and some env vars. Every MCP client wraps that primitive in its own config syntax, but the primitive itself doesn't change.

Canonical shape (the only thing you actually need to know):

{
  "command": "npx -y @aemrezorlu/sidecar-mcp",
  "env": { "SIDECAR_BACKEND": "ollama" }
}

For a from-source install, swap npx -y @aemrezorlu/sidecar-mcp for node /absolute/path/to/sidecar-mcp/dist/index.js.

Where each client stores it:

Example — VS Code Copilot (.vscode/settings.json):

{
  "github.copilot.chat.mcp.servers": {
    "sidecar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@aemrezorlu/sidecar-mcp"],
      "env": { "SIDECAR_BACKEND": "ollama" }
    }
  }
}

Example — Codex CLI (~/.codex/config.toml):

[mcp_servers.sidecar]
command = "npx"
args = ["-y", "@aemrezorlu/sidecar-mcp"]

[mcp_servers.sidecar.env]
SIDECAR_BACKEND = "ollama"

The command/args split varies by client (some take a single string, some take an array); the primitive above is what every client is configuring.

Tool reference

bulk_read

Returns: the worker's text summary. The full file content never appears in the caller's context.

Response footer: every bulk_read reply ends with a one-line footer for cost spot-checks:

---
sidecar: model=<model>, backend=<backend>, tokens=<in> in / <out> out

(or tokens: n/a if the backend didn't report usage). Footer is included automatically; no flag to disable in MVP.

Example call:

{
  "paths": ["src/Service.java", "src/Handler.java"],
  "question": "What does this service do and what are its key methods?"
}

Worker prompt shape (for debugging):

<files>
<file path="src/Service.java">…</file>
<file path="src/Handler.java">…</file>
<!-- unreadable: path/to/binary.bin — binary file -->
</files>

<question>
What does this service do?
</question>

How it works

main agent (whatever MCP client you wired it into)
   │
   │  MCP stdio JSON-RPC:
   │  {"method":"tools/call","params":{"name":"bulk_read", ...}}
   ▼
sidecar-mcp subprocess
   │
   │  reads files, wraps in XML, POSTs to:
   ▼
worker model (any configured backend — Ollama / OpenAI / Anthropic / proxy — cheap)
   │
   │  returns ~600 token summary
   ▼
back to main agent as tool result

The full file content stays between sidecar-mcp and the worker. The main agent only ever sees the summary.

Security

bulk_read reads files from the local filesystem and ships their content to the worker LLM. Two layers scope what the worker can see:

• SIDECAR_ALLOW_ROOTS is a comma-separated allowlist of absolute paths. Anything outside is skipped with path outside allowed roots. If unset, sidecar-mcp defaults to the current working directory and prints a one-line warning to stderr at boot. Set it explicitly for any non-dev use.

• Symlink escape is blocked. Every file is checked both lexically (path prefix) and via realpath (canonical target). A symlink inside allowRoots that points outside is rejected with path resolves outside allowed roots (symlink escape). allowRoots are also realpath'd, so /var vs /private/var style mounts collapse consistently.

Per-file safety: SIDECAR_FILE_MAX_BYTES (default 512 KB) skips oversize files, NUL-byte sniff skips binaries, and the worker's reply is the only thing that returns to the MCP client — the main agent's context never holds raw file content.

Cwd default is a footgun. Launching from $HOME exposes ~/.ssh, ~/.aws, .env to the worker. For any deployment, set SIDECAR_ALLOW_ROOTS to a tight scope (e.g. the project root) instead of relying on the default.

Limitations

• Non-streaming. Worker replies are returned as one text blob.

• No code_write. Bulk boilerplate generation is out of scope for MVP. If you need it, build a separate tool.

• Claude Code hook layer is opt-in. Auto-redirect of large Read/Bash cat|head|tail calls to bulk_read lives in extras/claude-hooks/ and is not installed by default. See extras/claude-hooks/README.md to wire it into ~/.claude/settings.json.

• SIDECAR_ALLOW_ROOTS defaults to cwd. Files outside are skipped with a warning. Set explicitly for stricter scoping.

Development

git clone https://github.com/dEMonaRE/sidecar-mcp.git
cd sidecar-mcp
pnpm install
pnpm dev          # run with tsx watch
pnpm test         # vitest
pnpm demo         # offline self-check (fake backend, prints prompt + reply)
pnpm build        # tsc → dist/
pnpm pack         # build a tarball to verify before publishing

Manual smoke test with real Ollama:

ollama serve &
ollama pull llama3.1:8b
SIDECAR_BACKEND=ollama sidecar-mcp &   # in one terminal
# Wire into your MCP client (Claude Code, Copilot, Codex) and call bulk_read.

License

MIT — see LICENSE.