scoped-mcp tackles credential sprawl in multi-agent Claude Code setups

Ted Murray's post on Dev.to describes a structural credential and tool-scoping problem in Claude Code's MCP server architecture. When users configure MCP servers in `settings.json`, all environment variables — API keys, database tokens, webhook URLs — are loaded into the full session environment and made available to every server and agent in that session, regardless of whether a given server actually needs them. A file operations server, for example, ends up holding a notification webhook URL it will never use. Murray argues this creates an unnecessarily large blast radius: a hallucinated tool call, a prompt injection in a tool response, or a confused agent acting on a backend it shouldn't know about could expose every configured credential at once.

The result is `scoped-mcp`, a per-agent proxy process that connects to the agent over `stdio` like any MCP server.

The problem compounds in multi-agent setups. While designing `homelab-agent` — a platform for running durable, multi-phase infrastructure builds with pools of parallel Claude Code agents — Murray encountered four compounding issues: every agent in a pool holds every credential; read-only agents can see write tools for backends they have no business touching; agents share workspaces with no boundaries, enabling one agent to overwrite another's data; and with 12 MCP servers each contributing their full tool lists, each session burns 15–30K tokens on initialization overhead before any work begins, scaling to 300–600K tokens across 20 concurrent agents.

Murray surveyed existing solutions — aggregation gateways, access control proxies, and enterprise gateways — and found none combined all four requirements: tool filtering, resource scoping, credential isolation, and unified audit logging. The result is `scoped-mcp`, a per-agent proxy process that connects to the agent over `stdio` like any MCP server. It reads a YAML manifest file per agent role that declares exactly which modules, modes (e.g., `read` vs. `read/write`), and credentials are permitted. Tools not listed in the manifest are never registered and are invisible to the agent entirely — it is not a filtering layer on top of a full tool surface, but a narrower surface from the start. Murray notes the tool was itself built using the same multi-agent pattern it is designed to protect, with a research agent scoping the problem space and a dev agent implementing the code, each running under the constraints `scoped-mcp` enforces.

Key facts

1. 01Claude Code loads all MCP server environment variables into a single shared session, giving every agent access to every configured credential regardless of need.
2. 02A hallucinated tool call or prompt injection could expose every credential across all configured MCP servers — not just one.