MCP & tool configuration for coding agents

Most MCP servers are prototypes with permissive defaults: fine for a demo, dangerous once an agent can read your filesystem. The failure modes are concrete — silent data exfiltration, an agent running rm -rf somewhere it shouldn't, or API keys ending up in someone's training data. You don't need a SIEM or a threat-model document. Five protections cover solo scale and take about 30 minutes:

• Sandbox untrusted servers. If you can't read every line of a server, it doesn't get host access. Run it in Docker (or a VM/LXC). A baseline is docker run --rm --network=none --read-only --tmpfs /tmp -v $(pwd)/sandbox:/data <server>. Turn off networking for anything that doesn't legitimately need it; allowlist specific hosts for the ones that do.
• Use a tool allowlist, not a denylist. Agents default to "call anything." List the tools you've actually vetted by name, and add a new server's tools one at a time — never a whole namespace via wildcard.
• Move secrets out of the env your agent can see. If the agent has shell access it can read .env. Fetch secrets at runtime from a secret manager (export TOKEN="$(op read ...)") so nothing sensitive lives in the repo or the environment file.
• Log every tool call locally. tee MCP output to a timestamped file. When a run feels off, you grep the log; when it is off, you have evidence of what triggered it.
• Keep a kill switch. One alias that pkills every agent and stops MCP containers, for when a prompt injection from a web page sends an agent off the rails.

The full setup takes about 30 minutes; maintaining it costs roughly a minute per new tool. Skip the enterprise-flavored advice — the right question at solo scale is "what would I regret skipping?"

MCP solved capability and created a supply-chain problem. When a citation-verification server, a curated DevOps/SRE list, and an AI gateway for provider fallbacks all show up at once, the base model stops being the whole workflow — and every new server is code you're trusting with tool access. Two habits help.

First, separate trusted tools from experiments, explicitly. Keep a short list of servers you've vetted (ideally pulled from a curated or official catalog) apart from the ones you're just trying out, and don't let an experiment quietly inherit the same permissions as a proven tool. A new server on your machine is a new thing that can edit files, call APIs, or spend budget.

Second, treat verification as a workflow primitive, not an afterthought. Before a server's output becomes part of your work, you want to see what server was invoked, what evidence it returned, and whether a deterministic check passed — not just a confident chat message. The agent's confidence is not evidence. This matters most where verification sits near execution: if a server can edit files, call APIs, or cite sources, the check has to happen before that output lands.

Routing records matter for the same reason. Provider changes affect quality, cost, and risk, so a later review should be able to see which model did the planning, which did the edit, and which verified the result. That compact trail of decisions — which server ran, what it returned, which check passed — is what lets AI-assisted work survive a handoff instead of being reconstructed from memory.

This shows up in every editor's issue tracker: the integrated terminal's PATH differs from your normal terminal, aliases are missing, nvm use fails. It isn't a bug — it's which kind of shell the editor spawns. A shell is one of three types:

1. Login shell — runs ~/.zprofile then ~/.zshrc (Terminal.app, most SSH sessions).
2. Interactive non-login shell — runs only ~/.zshrc (tmux panes, most editor terminals).
3. Non-interactive shell — runs neither (scripts, task runners).

If your nvm/pyenv/rbenv or PATH setup lives in .zprofile, an editor terminal that spawns interactive-non-login never loads it — so you see missing aliases and "command not found."

The quick fix is to force login mode. In Cursor/VS Code settings, add a profile with "args": ["-l"] and make it the default; for JetBrains set the shell path to /bin/zsh -l; for tmux, set -g default-command "${SHELL} -l".

The durable fix is putting setup in the right file: environment variables that need to exist everywhere in .zshenv, once-per-login setup in .zprofile, and everything interactive (aliases, nvm/pyenv init) in .zshrc — which every interactive shell loads regardless of login status. Verify with echo $PATH; type nvm in both Terminal.app and the editor terminal; the output should match.

This matters for agents specifically. Claude Code, Codex CLI, and Aider inherit the editor terminal's environment. Wrong PATH means the agent runs the wrong node; a missing direnv/env load means the wrong DATABASE_URL. You get bugs that look like AI hallucinations but are really environment mismatches — an agent making correct decisions from incorrect context.

The complaint is specific: Claude Code reads CLAUDE.md, Cursor reads .cursorrules, Copilot reads .github/copilot-instructions.md, others read AGENTS.md. Team instructions drift across Claude, Cursor, Copilot, Windsurf, Cline, and Gemini until no two tools carry the same rules. One developer built a sync tool (Nymor) specifically because agent rule files fragment this way and teams want one canonical source.

It's the same problem teams hit moving from single-user AI experiments to shared workflows: agent rules, MCP servers, prompts, and skills all have to line up across the team, or every person re-derives the setup from scratch. The durable pattern isn't picking one tool — it's keeping the rules, routing, and setup in one place and projecting them into each tool's expected file, so a change happens once instead of six times.

Two things make this worth doing early rather than late. Drift is silent: these files are read by tools, not humans, so a section that quietly disappeared two months ago produces wrong agent behavior with no error to catch it. And retrofitting costs more: once the setup has scattered — config in different files, context in dead chats, the "real" rules living only on one person's machine — you're reconstructing the workflow instead of improving it. Build the shared layer up front and a new developer starts from a known setup instead of reverse-engineering the last twenty prompts.

CLAUDE.md files drift for four reasons: they're read by tools not humans (so breakage is invisible), they aren't quite "code" (reviewers skim them), they aren't quite "docs" (doc review doesn't apply), and they're template-like (people delete sections they don't understand). The drift is rarely a deletion you notice — it's the security section that quietly vanished during an unrelated change two months ago.

The fix is the same as for any team-wide standard: a CI check. Enforce only cross-repo policy — security ("never commit secrets"), forbidden actions ("no --no-verify", "no force-push to main"), branch/PR rules, the list of authorized AI agents — and leave repo-specific sections (architecture, test commands) alone. The minimal version is a bash script that greps for required section headers and required phrases and exits non-zero if any are missing, wired into a GitHub Action on pull_request.

For 10+ repos, don't copy the script everywhere. Keep the required list in one central policy repo and have each repo's CI curl it and compare — updating policy becomes a single PR that every repo picks up on its next run. Some teams prefer auto-fix (append missing boilerplate) over fail-on-missing; that works for identical boilerplate but not for sections needing repo-specific content, so fail-on-missing is the better default.

This matters more for AI than for humans. An assistant reads the file cover-to-cover and treats every line as authoritative, so a missing "no --no-verify" line means it will happily bypass your pre-commit hooks. A 30-line script in CI is the cheapest team-wide AI policy enforcement you can buy.

Once you move past generic code generation, MCP setup gets domain-specific fast. A real example from the threads: making Claude useful for Power BI work through MCP — prompts, Skills files, semantic-model cleanup, DAX, and measure creation. But the setup is only half the job; the other half is trusting the result.

Domain work multiplies the action surface: shell commands, package installs, migrations, file deletes, network calls, generated credentials, and test runners that can mutate local state. A chat transcript can't be the control plane for that. Three things make a domain MCP setup usable.

Context has to be searchable, not just present. A big repo is full of old experiments, generated files, and stale docs; giving the agent file access isn't the same as giving it useful context. The workflow should show which folder, file, or prior decision is actually in play, so the agent doesn't spend budget rediscovering what you already know.

Guardrails belong around actions. Distinguish read-only inspection from destructive commands, make approval decisions visible, and let a project declare which tools are allowed and which steps need a human. The point isn't to slow the agent down; it's to stop confusing speed with permission.

Runtime proof beats a polished explanation. Logs, command output, test results, and a link between the final diff and the run that produced it. Without that trail, review turns into archaeology — and false progress (an agent looping the same search, or claiming a test passed without showing the command) stays hidden. The pattern generalizes past Power BI: any domain server you add needs searchable context, action guardrails, and an evidence trail before you can trust its output.

AI coding has spread from one assistant into a messy toolchain: Claude Code plugins with hooks/MCP/skills, Cursor users tracking whether specific Anthropic models are even available in their IDE, and a broader shift from cloud/model-locked agents toward bring-your-own and local models. Routing everything through the strongest model makes cost unpredictable and feedback slow; routing everything through the cheapest pushes quality failures downstream into debugging.

The practical answer isn't a universal model choice — it's deciding, per task, which one deserves expensive reasoning and where proof of completion has to appear. Two realities make this a config problem rather than a taste problem.

Model switching alone doesn't fix bad execution. A cheap model repeating the wrong tool calls is still expensive; a strong model working from stale context still wastes time. You need to see where tokens, time, and retries are going before you can decide whether the model, the prompt, or the workflow is the bottleneck.

Provider churn shouldn't rewrite your setup. Speed changes, billing changes, and quota 429s all push from different angles, and none is solved by loyalty to one provider. You want a layer above the provider that remembers the project rules and lets you swap engines without changing the whole operating model.

Visible routing also makes model comparisons less theatrical. If you can see which model planned, which edited, and which verified — plus what each one cost — you judge a workflow by operational quality instead of by one impressive answer.

This is the failure that turns an agentic loop into an expensive no-op: the agent calls a tool, the tool returns a result, and the model acts as if it never arrived — repeating the same call, or answering from memory instead of the data it just fetched. One builder hit all of it at once writing a no-dependency Node/llama.cpp harness: attention drift, ignored tool results, and the same tool called on repeat. Four causes explain almost every case.

The result is buried in a bloated context. A filesystem read that dumps 40k tokens pushes the model's own question out of its effective attention window, so it 'forgets' what it was doing. This is exactly why one filesystem MCP server (SurgicalFS) added response budgets — cap and paginate tool output, and summarize large reads, so the result stays near what the model is actually attending to instead of drowning it.

The result isn't returned in the shape the model expects. If you hand a tool result back as a plain user string instead of a proper tool/function message tied to the originating call id, many models never register it as the answer to their call — so they call again. Return results as structured tool messages, matched to the tool-call id.

There's no dedup or loop guard. Cache identical calls within a run and return the cached value with a note; detect a repeated call signature and stop, rather than letting the agent burn tokens re-asking the same question.

You can't see it happening. Without a log of each call's arguments, its result, and whether the next step referenced that result, 'the agent ignored the tool' is a guess. Make the tool loop observable first — the fix is usually obvious once you can watch a result come back and get dropped.

Yes, and it is worth separating from the question of whether an MCP server is safe to install. Install-time trust is about what a server can do to your machine. Prompt injection is a runtime attack: untrusted content the agent reads as data gets interpreted as instructions. The channels are everywhere an agent ingests text it did not author — a web page it fetches, the JSON a tool returns, a file in the repo, a README inside a dependency, the output of a subagent you delegated to. If any of that carries "ignore your previous instructions and do X," a naive agent may comply, because to a language model there is no hard boundary between the task and the material.

The sharp version people hit is the subagent that returns a payload instead of doing the work — a review subagent that comes back with embedded directives rather than a review, and the parent agent acts on them without ever making the tool calls it claimed. Nothing in a chat transcript makes this visible; you see a confident answer, not the injected instruction that produced it.

You cannot prompt your way out of this reliably, so treat it structurally:

• Keep untrusted content labeled as data. Fetched pages, tool results, and third-party files are inputs to reason about, never instructions to obey. The higher the privilege of the next action, the more suspicious an unexpected imperative in that content should be.
• Make tool calls and subagent returns inspectable. If you can see exactly which tools ran and what a subagent actually returned, an injected instruction that produced an out-of-band action stops being invisible.
• Vet what you install before it runs. Skills, MCP servers, and repos pulled from strangers are code and prompts you are adopting; scan them, read them, and prefer ones with a real source and history over a convenient copy-paste.
• Bound the blast radius. An agent that can be hijacked should still hit an approval gate before anything destructive, so a successful injection stalls instead of executing.

The model is easy to swap; the trust boundary around what it reads and runs is the part you own.

The AI tools gold rush created a perfect phishing surface. New CLIs ship weekly, everyone's used to downloading installers for tools that didn't exist last month, and attackers noticed: search ads that display a legitimate domain — a real-looking claude.ai link — while routing the click to a lookalike installer. One recent case ended with malware on the machine and a drained rewards account. The victim did nothing unusual; "search for the tool, click the top result" is how most people install everything.

The rules are old, but the reflexes need rebuilding for this ecosystem. Never install from an ad — type the vendor's domain yourself, or use a package manager where the publisher is pinned (npm, brew, an OS store) rather than a downloaded binary from a search result. Check what you're running before you grant it anything: a signed installer from the actual vendor, an official repository, a checksum when one is published. And remember that everything downstream inherits the compromise — a poisoned dev tool runs with your git credentials, your SSH keys, your browser sessions, and every token in your shell environment.

The same skepticism applies to the layers you bolt on after: MCP servers, agent skills, and plugins are executables with your permissions, not configuration. An unofficial "community server" for a popular service deserves the same scrutiny as an installer from an ad. If you suspect you've already run something dirty: rotate tokens first, then check shell rc files, MCP configs, and scheduled tasks for additions you didn't make — that's where persistence hides.

Two different costs are stacking here. The first is the context tax: every connected server's tool definitions sit in the prompt on every turn, whether or not you use them. Five research servers can be several thousand tokens before you ask anything — paid on every message, all session.

The second is worse: silent failure. When a fetch returns a Cloudflare interstitial or a consent wall, the agent gets text, and text looks like content. That's where confident summaries of pages nobody read come from.

What collapses it:

• Connect only what this project needs. Research tooling doesn't belong in a project that never leaves the repo. Per-project server sets beat one global pile.
• Escalate instead of specialising. Plain HTTP first; only fall back to a browser when the response is obviously a block or a JS shell. Most pages need no browser, and the escalation ladder replaces four separate servers.
• Normalise the output. One shape — URL, final URL after redirects, status, extracted text, and a flag for "this looked like a block page" — lets the agent reason about failure instead of summarising it.
• Make failure loud. A blocked fetch should return an error the agent can't mistake for content. This one change removes most research hallucinations.
• Measure the passive cost. Count the tokens your tool definitions occupy before the first message. It's usually the cheapest optimisation available and nobody looks at it.

A dead MCP server is the worst kind of cost because it's invisible and constant: every request silently carries its tool schema whether or not anything ever calls it, and it does this across every worktree that inherited the config. You don't notice because nothing breaks — the bill and the context just run higher than they should, forever, until you go looking.

Profiling your own transcripts is exactly the right instinct; the fixes follow the findings:

• Audit what's actually in the context, per request. A schema for a server you never call is pure overhead. If a tool hasn't been invoked in months, its schema shouldn't be loaded — remove or disable the server, don't just ignore it.
• Kill config that propagated by inheritance. A zombie MCP entry copied into every worktree has to be removed at the source, or it returns on the next clone.
• Find the repeated large reads. A 5,600-line file read on every session is a context tax; split it, summarize it, or point the agent at the section it needs.
• Watch failed tool calls. Hundreds of failed invocations are retries you paid for; a tool that fails constantly is worse than one that's simply missing.

The theme is consistent: context bloat is rarely one big mistake, it's a dozen quiet ones that only a look at the real transcripts surfaces. Cache efficiency improves on its own once the dead weight is gone.

Agent configuration is executable behavior living outside your source tree, and it gets none of the checking your code gets. No compiler reads a hook definition. No test fails when a skill's allowed-tools list omits a tool that skill actually uses. The failure mode is silence: the hook never fires, the skill never triggers, the MCP server exits on startup, and the agent carries on as though everything is wired — producing work that looks fine and skipped the guardrail you thought you had.

The checks worth automating split into two groups.

Wiring — does this do anything at all?

• Hooks pointing at a script that doesn't exist, or a matcher that can't match any real event.
• Skills with no trigger, or an allowed-tools list missing a tool the skill's own instructions call.
• MCP servers declared but failing to start, and servers that start but expose zero tools.
• Duplicate definitions across global and project config, where precedence isn't what the author assumed.

Safety — what does this permit?

• Permission rules broad enough to auto-approve destructive commands, and allowlist entries a shell can trivially escape.
• Tool schemas whose descriptions carry instructions rather than descriptions — the injection surface people forget is a surface.
• Self-invoking skills and subagent definitions with no depth bound, which is how one review command becomes a hundred sessions.
• Secrets referenced by literal value instead of an env indirection.

The false positives that make this kind of check unusable are the stylistic ones — flagging a long prompt, or a permission that's broad on purpose. Keep the rules mechanical: something is unreachable, something is undefined, something is unbounded. Those are checkable facts, and they're the ones actually costing you runs.

Manual testing exercises the path you designed. The agent exercises the protocol, and that's where the differences live.

Four gaps produce most "works locally, breaks in the client" reports:

• Transport and lifecycle. You test a function; the client launches your command as a subprocess, speaks JSON-RPC over stdio, and expects a correct initialize handshake. Anything your server prints to stdout that isn't protocol — a stray log line, a startup banner, a leftover debug print — corrupts the stream. Logs belong on stderr, always.
• The schema is the real contract. The agent doesn't read your README; it reads the tool schema and generates arguments from the description. Vague descriptions and loose types mean the model sends plausible-but-wrong input, so schemas need testing as specifications, not documentation.
• Failure paths, which are most of real usage. Happy-path testing skips the cases that dominate live runs: missing required fields, wrong types, IDs that don't exist, timeouts, oversized responses. An error the model can act on — field 'path' must be absolute — recovers. A stack trace or a silent empty result sends it into a retry loop.
• Response size. A tool returning 40k tokens technically works and practically breaks the session it's used in.

So build a harness that launches the real command, completes initialization, lists tools and asserts their schemas, then calls each tool with valid, invalid, and boundary input — asserting that failures come back as structured, readable errors rather than crashes. Run it in CI. The goal isn't coverage of your logic; it's proof that a model driving your server through the protocol can succeed, and can fail informatively when it doesn't.

Mostly no — and the instinct to wrap everything is what makes these copilots unusable. Every connected MCP server injects its tool schemas into every request, whether or not the task touches it. A handful of broad servers can cost tens of thousands of tokens before you type a word, and tool-selection accuracy drops as the menu grows. The question per system isn't "can I expose this?" but "does the model lack something it needs?"

Three cases, three different answers:

Tools with a well-known CLI — kubectl, the cloud CLIs, git, psql. The model already knows these far more thoroughly than your wrapper's schema will ever teach it. Give it a shell and let it use them. Wrapping kubectl in MCP spends context re-teaching something already learned, and adds a layer where your wrapper's bugs become the model's confusion.

Systems where the gap is organisational, not technical. Which service owns which host, what the naming convention encodes, which cluster is production, who gets paged. This is where curated context earns its keep, and it isn't a tool — it's a service catalogue, a compact document the agent reads. Most complaints of the form "the agent doesn't understand our infrastructure" are this, and no amount of extra API surface fixes it.

Genuinely idiosyncratic internal APIs with no CLI. Worth an MCP server: narrow, with a few purpose-shaped tools ("current alerts for service X"), not a generic HTTP passthrough that hands back 400KB of JSON for the model to parse in-context.

Then the property that makes any of this deployable: default operational access to read-only, with writes as a separate, explicitly granted path. An agent that can describe, correlate and diagnose is enormously useful and cannot cause an outage. The same agent with apply rights is a change-management problem. Keep those as different grants, not as different wording in a prompt.

Finally, attach evidence. An infrastructure recommendation without the query and timestamp behind it can't be verified and shouldn't be acted on — half the value here is that a human can check the reasoning against the same data. And keep token cost attributable per work item, or the copilot quietly becomes the most expensive way to read a dashboard.

The capability is real and the concern is the right one, because visual context has a property text context doesn't: it captures things you never chose to share. A screenshot taken to show a rendering bug also contains the notification that just arrived, the adjacent tab, the customer name in the window behind. Text context is what you pointed at. Visual context is whatever happened to be there.

What a well-bounded visual surface looks like:

• Scoped to a task, not to a session. Capture attached to a specific question — "why does this layout break" — and released when it's answered. An always-on frame buffer is a different product with a different risk profile, and it should be an explicit choice rather than a side effect of installing an MCP server.
• Expiry by default. Frames age out. A screenshot's usefulness has a half-life measured in minutes; its liability doesn't decay at all.
• Read and act separated. "Look at my screen" and "click things on my screen" are not the same grant. Bundling them is how a debugging aid quietly becomes a remote-control surface.
• Provenance on every frame. When it was taken, from which window, and which agent turn consumed it — so the evidence behind a decision is inspectable afterwards rather than merely implied.
• A visible capture indicator. Ambient capture with no persistent signal that it's running is where trust goes to die, regardless of how good the privacy policy is.

The general test for any MCP server exposing a sensor: can you say exactly what it captured in the last hour, and delete it? If not, you've installed something with a much larger surface than the feature you actually wanted.

You have already found the real distinction, so start by naming it: a rules file is a request and a permission check is a mechanism. Everything in CLAUDE.md, skills, and system prompts competes for attention against the task and loses often enough to be worthless as a guarantee. A deny rule and a PreToolUse hook are not competing with anything — they run whether or not the model agrees. Anything you actually depend on belongs in the second category.

Then the harder half: enforcement points are per-harness by construction. Claude Code has hooks and permissions, Cursor has its own model, Codex another. Writing the policy three times means it drifts, and drift in an enforcement layer is worse than having none, because you believe you are covered.

What travels, in descending order of portability:

• Environment-level denial. A credential the agent does not hold, a network path it cannot reach, a filesystem it cannot write. This works in every harness because it lives in none of them. Push down whatever you can.
• Repo-owned policy as data. One declarative file listing allowed tool paths, denied fallbacks and required preconditions, with a thin adapter per harness reading it. You still write the adapters, but the policy has one home and one diff.
• Verification after the fact. A check that fails when work was produced through a disallowed path. Weaker than prevention, but harness-independent, and it catches the case you did not anticipate.

Two specifics from your situation. Cover the alternate paths — denying a read tool while leaving shell access open denies nothing, and models find the open door quickly. And treat permission changes as code: they regress, and a rule that silently stopped applying looks exactly like a rule that is working. Keep a small test that attempts the forbidden path and asserts it fails, and run it whenever configuration changes.

An agent's debugging quality is bounded by the detail in its tool results, and most tools return the shape a human needs — a status line and a body — because a human fills in the rest from the terminal, the network tab, and what they know about the system. An agent has none of that. Give it a bare 401 and it will produce a confident hypothesis, because producing hypotheses is what it does when information runs out.

What a result needs to carry:

• The full exchange. Final URL after redirects, request headers with secrets masked, the body actually sent, response headers, and the response body rather than a truncated preview. Most misdiagnosis traces back to a request that was not the one you thought was sent.
• Which environment resolved, and to what. An empty or unresolved variable is among the most common failures and is completely invisible in a status code.
• Structured assertion failures. Not "test failed" but the field, the expected value, the received value, and the path. That converts a guess into a lookup.
• Timing across the transport layer. DNS, connect, TLS, first byte. It separates "the service rejected it" from "we never reached the service", which are different repairs.
• A failure classification. Network, auth, validation, server error, assertion mismatch. Naming the category stops the agent ranging across all of them.

Two design points matter as much as the content. Run the agent's request through the same engine the interface uses — if the paths differ, you are debugging a request nobody will ever send in production. And keep requests in the repository as files, so a run is reproducible, reviewable in a diff, and the agent discovers what already exists instead of hand-rolling a new call every time.

Tools that return evidence make agents debug. Tools that return verdicts make agents speculate.