Why I Stopped Letting Claude Shell Out for Security Scans

A founder I know spent last Tuesday night debugging what he thought was a Claude bug. He'd wired up Claude Code to his repo with the default shell tool, asked it to "scan this codebase for secrets and SQL injection," and watched it confidently produce a clean report. Zero findings. He shipped to staging. Twelve hours later his Datadog alert fired on a Postgres error trace that exposed a hardcoded service account key in a config file Claude had supposedly scanned.

He called me at 11pm. We screen-shared. The problem was almost funny once we saw it. Claude had run cyscan — correctly, with the right flags — against the wrong directory. It had cd'd into a subfolder earlier in the conversation to read a file, never cd'd back, and then run the scan from there. The scan completed in 400ms because there were six files in scope. Claude wrote up a confident summary of those six files, called it a codebase audit, and moved on.

That's not a Claude failure. That's a tool design failure. Shell is a terrible interface for a security scanner when the caller is a probabilistic agent with no model of working directory state, no schema for what "done" looks like, and no way to know if the tool it just invoked actually understood the request. The whole exchange was vibes. The agent produced confident output because shell tools produce stdout and stdout looks like an answer.

I've been building Cybrium for two years now, and the single most important architectural decision we made in the last six months was to stop telling people to invoke our scanners via shell. Today everything routes through an MCP server. Ten tools. Typed inputs. Structured outputs. No working directory drift. Let me explain why this matters and what we learned along the way.

The thesis

If your agent talks to security tooling over a shell, you've built a system where the agent's confidence is decoupled from the scanner's actual coverage. MCP fixes this by making the contract between agent and tool explicit, machine-checkable, and inspectable after the fact. This isn't a UX upgrade. It's the difference between a security pipeline you can audit and one you cannot.

What "default shell tool" actually gives you

When Claude Code, Cursor, or any agent runs cyscan --path . --format json through a bash tool, here's what's actually happening. The agent constructs a string. The string goes to a shell. The shell maintains its own state — working directory, environment variables, prior exit codes — that the agent only partially observes. The scanner runs, writes to stdout, maybe also stderr, exits with a code, and the agent reads it all back as a single blob of text that it then has to parse.

Every step there is a place where things break in ways the agent can't see.

The agent doesn't know if cyscan was the binary it thought it was, or some alias, or a different version on PATH. It doesn't know if the path it passed was a symlink, was expanded by the shell glob, or got truncated. It doesn't know if stderr contained warnings that materially change the meaning of stdout. It doesn't know if the exit code maps to "clean scan" or "scanner crashed after partial run." It just sees text.

And here's the part that haunts me as someone shipping a security product: the agent doesn't know how many rules ran. If cyscan ran 1,815 rules across 75+ languages on a 200-engineer monorepo, that's one outcome. If it ran 12 rules because it only found two file types in the subdirectory it was actually pointed at, that's a completely different outcome. Stdout looks similar in both cases — a JSON array of findings, possibly empty. The agent summarizes "no findings." The CISO sleeps poorly.

Shell tools optimize for human flexibility. Humans cross-reference, notice anomalies, get suspicious when a scan finishes too fast. Agents don't, at least not reliably, and certainly not under pressure when they're four turns deep in a conversation about something else.

What MCP changes structurally

Model Context Protocol is, at its core, a typed RPC layer between agents and tools. That sounds dry. The implications are not.

When Claude calls cyscan_repository through our MCP server, it isn't writing a shell string. It's calling a function with a typed schema. The schema declares that path is required, that it must be an absolute path, that language_filter is an optional enum, that rule_packs defaults to "all 1,815." The MCP server validates the call before our scanner ever runs. If the agent forgets a required arg, the call fails with a structured error the agent can actually reason about — not a bash error that says "missing argument" in some format the agent has to text-match against.

The response is structured too. Not stdout. A JSON object with fixed fields: scan_id, files_scanned, rules_executed, findings, coverage_metadata, duration_ms. The agent doesn't have to parse anything. It just reads files_scanned. If that number is 6 when the repo has 4,000 files, the agent has a fighting chance of noticing, because files_scanned is a first-class field that the agent's system prompt can be told to check.

This is what I mean by making the contract machine-checkable. With shell, "did the scan actually scan the thing" is a vibes question. With MCP, it's a field.

The ten tools and why ten

Our MCP server exposes exactly ten tools right now. I get asked sometimes why so few — surely a security platform has more surface area than that. The answer is that ten is the result of a lot of arguing about granularity.

Too few tools and each tool becomes a god-function with twenty parameters and the agent has to learn a sub-language to drive it. Too many tools and the agent's context window fills with tool descriptions before it's done a single useful thing. Ten was where we landed after watching agents actually use the server for three months.

The tools split roughly into three families. Code and repo scanning lives in cyscan-backed tools that handle static analysis across 75+ languages. AI-specific scanning lives in cyradar-backed tools that probe local inference endpoints — Ollama, vLLM, TGI, LocalAI, Triton, LM Studio, llama.cpp — for the kinds of misconfigurations that don't show up in any conventional vuln scanner. Web and API fuzzing lives in cyweb-backed tools that drive our 22 fuzz categories with 95% template-conversion fidelity against upstream community signatures.

Each tool does one thing. The agent composes them. That composition is where the real power lives, and it's also what shell tools fundamentally can't do, because shell composition happens through pipes and string parsing instead of through structured data the agent actually understands.

A concrete example

Here's the kind of workflow that's trivial with MCP and miserable with shell. Suppose I want my agent to do a full security pass on a new microservice: scan the source for vulns and secrets, then if any of the findings touch an AI inference path, probe the running inference endpoint for those specific issues, then if any of the findings touch an HTTP route, fuzz that route with relevant templates.

With shell, this is a small program. The agent has to invoke cyscan, parse the output, build a follow-up command, invoke that, parse, build another. Every parsing step is a place where the agent can hallucinate field names, miss findings, or get tripped up by formatting changes between versions. I've seen agents miss findings because they expected severity and got risk_level.

With MCP, here's roughly what it looks like from the agent's side:

1. call cyscan_repository(path=/repo/order-service)
   -> returns findings[] with structured types
2. for findings where category == "ai_inference":
     call cyradar_probe(endpoint=finding.endpoint, checks=["prompt_injection","model_extraction"])
3. for findings where category == "http_route":
     call cyweb_fuzz(target=finding.url, template_packs=relevant_packs)
4. call generate_report(scan_ids=[...])

The agent doesn't write parsing code. It doesn't construct strings. It calls functions on objects. When cyradar_probe finds a prompt injection vector against a llama.cpp endpoint, that finding is a typed object with a CVE-style identifier, a severity, a remediation hint, and a pointer back to the originating cyscan finding. The lineage is preserved. The audit trail is automatic.

You can build something similar with shell. People do. It involves jq, bash heredocs, and a lot of prayer. It is not robust to scanner version updates, scanner output changes, or agent context drift across turns. I have watched these pipelines work flawlessly for two weeks and then silently start dropping findings because someone added a field to the JSON output and the jq filter didn't match anymore. Nobody noticed for a month.

The state problem

This is the one I care about most, and it's the one that bit the founder I mentioned at the top. Shell sessions have state. Agents have an imperfect model of that state.

Working directory is the obvious one but it's not the only one. There's environment variables, which the agent often sets early in a conversation and then forgets about. There's PATH ordering, which can change which binary gets executed. There's shell history affecting tab completion if the agent uses it. There's locale settings affecting how filenames with non-ASCII characters get handled. There's umask affecting permissions on output files. Every one of these is a state surface the agent has to track or risk getting wrong.

MCP tools are stateless by default in the way the protocol is designed. Each call is a self-contained, fully-specified invocation. If you want state — say, a long-running scan whose results you want to retrieve later — that state is explicit and addressable. Our scan_id is a first-class thing. The agent passes it in, gets the same results back, can hand it to another tool. There's no "where am I in the filesystem" question because the filesystem isn't part of the protocol. Paths are arguments. Arguments are typed. The scanner resolves them against a known, fixed base.

This eliminates a whole class of failure mode that I genuinely believe is responsible for most agent-driven security incidents I've seen in the last year. Not zero-days. Not novel attacks. Agents scanning the wrong directory and confidently reporting clean.

Why one server and not ten CLI wrappers

I get the architectural question a lot: why does Cybrium ship one MCP server that exposes scanners, instead of three separate MCP servers wrapping cyscan, cyradar, and cyweb? Why couple them?

Because the findings need to talk to each other. A cyscan SAST finding about an unsafe deserialization in an LLM-output handler is interesting on its own. It becomes urgent when cyradar finds that the upstream inference endpoint accepts prompts from untrusted users. It becomes a P0 when cyweb confirms that the HTTP route exposing that handler is reachable without auth. None of those tools, in isolation, can tell you you have a critical incident chain. The MCP server holds the cross-tool context that makes correlation possible.

You could rebuild this on top of three separate MCP servers if you put a coordinator agent in front of them. People will try. I've tried. The coordinator agent has to know the semantics of findings from each scanner well enough to correlate them, which means baking scanner-specific knowledge into the agent's prompts, which means every scanner version bump becomes a prompt-engineering exercise. We did this. It was bad. Centralizing the correlation in the MCP server itself — where it can be versioned, tested, and updated alongside the scanners — is the better factoring.

The same logic, by the way, is why I don't believe in "bring your own scanner" MCP servers as a long-term architecture. Generic shells over arbitrary security tools sound great in a slide deck. In practice, the semantic gap between tools is where all the value lives, and a generic shell can't bridge it.

The recomposition

What's actually happening across the security tooling industry right now is a quiet recomposition. For fifteen years, the unit of integration was the CLI. You wrote a scanner that emitted SARIF or some custom JSON, and CI systems plumbed it together with bash. That worked when the orchestrator was a human writing YAML.

The orchestrator now is an agent. The agent doesn't write YAML. The agent makes decisions turn-by-turn based on what it just saw. The unit of integration for that world is not CLI output. It's a typed protocol that lets the agent reason about tools the same way a human reasons about a library. MCP is the first credible attempt at that protocol, and the products that win the next five years of security tooling will be the ones that ship native MCP surfaces, not the ones that bolt an MCP wrapper around their existing CLI as an afterthought.

The reason this is recomposition and not just integration is that once you have MCP-native tooling, the right unit of work changes. You stop thinking about "the scan" as a CI step and start thinking about "the security question" as an agent conversation. What did this PR change that touches PII? Did any of those changes introduce new attack surface that wasn't there yesterday? Are the inference endpoints we just deployed exposed to the same prompt injection that bit us last quarter? Those questions don't have YAML-shaped answers. They have agent-shaped answers, and they need tools the agent can actually drive.

What I'd do tomorrow if I were you

If you're using Claude Code or any agentic dev tool with shell access to security scanners right now, I'd do two things this week. Try our MCP server end-to-end on a real repo. The setup is one config block in your MCP client. Compare the findings count against whatever you're getting via shell. I would bet money you find a delta, and I'd bet that delta is in the direction of "MCP found things shell missed because shell was scanning the wrong scope."

The second thing: audit one of your agent conversations from last week. Pick a security-related one. Read the transcript. Count the number of places the agent made an assumption about shell state that it had no way to verify. Then ask yourself how many of those assumptions would still be assumptions if the tool had a typed schema.

You can pull the MCP server from cybrium.ai/mcp. The ten tools are documented there. Source for cyscan, cyradar, and cyweb lives in the same place. If you want to talk through your setup — especially if you're running local inference at scale and worrying about what your agents are actually seeing when they scan it — find me at anand@cybrium.ai.