DEV Community: Willian Pinho

Fail-close: the tool-access default every AI agent should ship with

Willian Pinho — Wed, 15 Jul 2026 14:45:52 +0000

Fail-close: the tool-access default every AI agent should ship with

I spent the better part of sixteen years building payment platforms. The first principle you internalize there, before any framework or pattern, is that the safe state is the closed state. A transaction that can't be verified doesn't get a "probably fine" — it gets declined. A service that loses its dependency doesn't keep serving stale balances — it stops. You learn to design systems where the failure mode is refusal, not improvisation.

Then I started building AI agents wired to real tools through MCP, and I watched the industry reach for the opposite default. Agents ship with broad tool access, allow-by-default, and a vague intention to "add guardrails later." That instinct is backwards, and it's going to cost teams who don't fix it before they go to production.

What "fail-close" actually means for an agent

Fail-close is a default you choose before the first tool is registered, not a guardrail you bolt on after. It means the default answer to "can this agent call this tool right now?" is no, and every yes is an explicit, scoped, auditable grant.

Most agent setups today do the reverse. You register a set of MCP servers, the model gets the full menu, and the only thing standing between a hallucinated plan and a destructive action is the model's own judgment plus maybe a confirmation prompt the user clicks through on autopilot. That's allow-by-default with a speed bump. It works in demos. It fails the first time the model decides that the cleanest path to "tidy up the staging database" runs through a DELETE it was never supposed to reach.

A fail-close agent inverts that. The agent starts with zero tool authority. Access is granted per tool, ideally per operation, against an identity and a context. When something is ambiguous — an unrecognized server, a tool outside the current task scope, a parameter that looks like it touches production — the system denies and surfaces the denial instead of guessing.

The distinction matters because models are non-deterministic and your blast radius is not. You cannot reason about what the model won't do. You can only constrain what the surrounding system will permit.

What breaks when you don't

The failures aren't exotic. They're the boring, predictable consequences of giving a probabilistic system deterministic power without a fence.

Give an agent read and write access to the same datastore and it will eventually write when you wanted it to read, because the boundary between "summarize these records" and "update these records" lives only in the prompt, and prompts are suggestions. Hand it shell access and a filesystem MCP, and somewhere down the line it runs a command that's correct in isolation and catastrophic in context. The same goes for an internal API reached with a service token: a confused enough plan will call the destructive endpoint with full confidence.

None of these require malice or a clever injection attack. They're just the base rate of a system that improvises under uncertainty being handed tools that don't. Add prompt injection from untrusted content the agent ingests, and the allow-by-default posture stops being a reliability problem and becomes a security one. The injected instruction doesn't need to break out of a sandbox if there was never a sandbox to break out of.

When I owned security review for shipping AI features, the question I asked first was never "is the model good." It was "what is the worst single tool call this thing can make, and who decided it was allowed to." If the answer to the second half was "nobody, it just had access," the feature didn't ship.

Governance and RBAC for MCP tools

One thing to be clear about first: the MCP protocol itself does not define roles, authorization, or RBAC. It describes how a client and server talk, not who is allowed to call what. That control plane is yours to build, and the natural place for it is the host application sitting between the model and the servers, the layer that sees every tools/call before it goes out and can decide to refuse it.

RBAC, scoped service identities, and audited grants already run every bank API and every CI deploy key in production. An agent is just another non-human principal asking for access. We have the machinery; we just have to stop pretending agents are a special category that gets to skip it.

Treat every MCP tool as a privileged operation behind role-based access control. The agent runs under an identity. That identity has a role. The role grants a specific, enumerated set of tool operations, scoped to an environment. A research agent gets read access to a knowledge base and nothing that writes. A deployment agent gets a narrow set of operations against staging and a separate, more guarded grant for production that requires a stronger gate.

Three things make this real rather than theatre.

Grants are per-operation, not per-server. Registering a database MCP server should not hand over its entire surface. Read and write are different privileges and belong to different roles, the same way you'd never give an analyst the production write credential just because they need to query.

Logging comes next: every tool call carries the identity, the role, the arguments, and the decision. You want to be able to answer "what did this agent do and what was it allowed to do" after the fact, with a trail, not a guess. The denials matter as much as the approvals; a spike in denied calls is a signal that the agent's plan has drifted from its scope.

And the dangerous grants pass through a human or a stronger policy gate before they're active. The point of fail-close isn't to block everything forever. It's to make sure that anything with real blast radius is a decision someone made on purpose, with their name on it.

The instinct, ported

I maintain an MCP server that runs across several agent clients, including Claude Code and Cursor. Building and operating it taught me how casually broad the default tool surface tends to be, and how little friction there is between a registered server and full access to whatever it exposes. The convenience is real. So is the exposure.

The reliability instinct from payments transfers cleanly: the safe state is the closed state, and you earn your way out of it one explicit grant at a time. We learned to stop treating "the agent can't do that yet" as a limitation. In production, it is the whole point.

The shift is small to describe and easy to defer. Choose the default before you register the first tool, not after the first incident. Everything else in this post is just the consequence of getting that one decision right while it is still cheap.

Sources

Model Context Protocol — Security Best Practices — the protocol's official guidance on consent, confused-deputy risks, and host-side controls.
Model Context Protocol — Tools — defines tools as model-controlled and calls for trust boundaries and human-in-the-loop confirmation.
OWASP — LLM01: Prompt Injection — why untrusted content can redirect an agent's actions.
OWASP — LLM06: Excessive Agency — the blast-radius risk of granting agents excessive functionality, permissions, or autonomy; recommends least-privilege scoping.
NIST — Least Privilege (glossary) — the foundational principle behind per-operation, role-scoped tool grants.

MCP in production: what I learned maintaining a server that works in Claude Code, Cursor, and Gemini

Willian Pinho — Fri, 03 Jul 2026 16:39:00 +0000

MCP in production: what I learned maintaining a server that works in Claude Code, Cursor, and Gemini

I maintain an MCP server that ended up running inside Claude Code, Cursor, and Gemini CLI. I did not plan for three clients. I built it for one, and then watched the other two start exercising paths I never tested, in ways the spec technically allowed but I never imagined.

That gap, between what the protocol permits and what a client actually does, is where most of the real lessons live. MCP looks simple on the surface: you expose a few tools, the model picks one and calls it, you return a result. That surface is exactly what fools you. The lessons below are the ones that only show up once a caller you didn't build for starts driving the server. Here is what survived contact with real usage, and what I deleted.

The model is a hostile-by-accident caller

Every backend engineer learns to treat input as untrusted. With MCP, the caller is a language model, and it is untrusted in a stranger way. It is not malicious. It is confidently wrong at a rate you do not see in human users.

A human who gets a confusing tool response stops and asks. A model retries. It will call your tool with a slightly mangled argument, get an error, reword the argument, and call again, sometimes a dozen times in a loop, because retrying is the cheapest action it has. Early on, one of my tools accepted a file offset and a length. A model would request a length that ran past the end of the file, get an error, and then ask for the same thing with the offset nudged by one. My logs filled with near-identical failures that no human would ever produce.

The fix was not better validation messages, though I added those. It helps to know that MCP gives you two different ways to signal trouble: a protocol-level JSON-RPC error, which tends to read as "the call itself was malformed," and a normal tool result flagged with isError, whose text the model actually reads and can act on. A hard protocol error invites the blind retry; a flagged result with a usable message invites a correction. The deeper fix was making the tool harder to misuse in the first place: clamp the range to the file instead of erroring, return what exists, and say so in the response. The model reads that, adjusts, and moves on. I stopped writing errors for a careful human reader and started writing responses a confused model could recover from without a loop. Once I saw it that way, half my "validation" work turned out to be the wrong shape entirely.

Fail-close is the only default that survives three clients

The deleted code is the part worth talking about. My first version had a permissive fallback: when a tool received an ambiguous or partially valid request, it tried to do something reasonable. That worked fine in Claude Code, where I had tested it. It broke in subtle ways the moment Cursor and Gemini drove it, because each client frames requests differently, truncates context differently, and decides differently when to call a tool at all.

A "reasonable default" is a guess about caller intent. Three clients meant three different intents behind the same malformed request, and my guess was right for one of them at best. So I tore the fallback out and made the server fail closed. If a request is ambiguous, refuse it and explain what a valid request looks like. The model gets a clear next step instead of a silent wrong answer.

This sounds obvious written down. It did not feel obvious while I was deleting code that worked in my one tested client to fix behavior in two I had not. Fail-close costs you a bit of apparent helpfulness and buys you the thing that matters more: a server that does the same predictable thing regardless of which agent is holding the other end. I have spent sixteen years on systems where the wrong silent default is how you lose money, including payment platforms serving over ten million users at three-nines uptime. Fail-close was not a new lesson. MCP just made me relearn it in an unfamiliar shape.

You cannot debug what you cannot replay

For the first weeks I had almost no idea what was actually happening inside a session. The model called my tools, things mostly worked, and when they did not, I had a vague bug report and no way to reproduce it. The non-determinism of the caller meant "run it again" produced a different sequence of calls.

What changed everything was logging each tool invocation as a structured record: the arguments as received, the response as returned, the timing, and which client sent it. Not application logs, an event trail I could replay and reason about. Once I had that, the loops surfaced, the client-specific framing differences were suddenly obvious, and the bugs stopped being ghost stories. Observability is not a nice-to-have you add when an MCP server gets popular. It is the thing that lets you understand a caller you do not control. I would build it on day one next time, before the first real user.

The second-order benefit surprised me. The event trail also told me which tools were never called. A model will quietly ignore a tool whose description does not earn its place, and you will never know unless you are counting. I removed two tools that looked useful to me and were invisible to every model that touched the server.

Tool descriptions are an interface, not documentation

The part I underestimated most: the model chooses tools based on their names and descriptions, and nothing else. There is no onboarding, no docs site, no support channel. The description is the entire contract, and it is read by a system that interprets language statistically rather than literally.

Tightening descriptions moved usage more than any code change I made. A tool that was being called in the wrong situations got called correctly once I rewrote its description to state plainly what it was for and what it was not for. This is closer to API design than to writing docs, and it rewards the same discipline: name the thing precisely, scope it narrowly, say what it does not do. I had shipped a KYC AI pipeline in three weeks once by being ruthless about scope, and the same instinct applied here. A narrow tool with a sharp description beats a flexible tool the model cannot reliably aim.

What this points at

None of this is exotic. It is ordinary production engineering, applied to a caller that behaves unlike any client you have built for before: non-deterministic, retry-happy, and reading your interface through a probabilistic lens. The teams I see struggling with agents in production are not failing at the model layer. They are failing at the boundary, where governance, fail-close defaults, and observability decide whether an agent is a reliable colleague or a liability you cannot debug.

So if you take one thing from this, let it be where to point your attention. The interesting engineering with MCP is not in the model and not in the tools. It is in the thin layer between them, the part that is easy to skip in a demo and impossible to skip in production.

Sources

Understanding MCP servers — server concepts (modelcontextprotocol.io) — tools are model-controlled: the model discovers and invokes them based on their names and descriptions.
MCP specification, server tools (2025-06-18) — tool definition (name, description, input schema) and the two error-reporting mechanisms: protocol-level JSON-RPC errors versus a result with isError set, whose text the model can read and recover from.
MCP architecture overview (modelcontextprotocol.io) — host, client, and server roles, and why the boundary between them is where production behavior is decided.
MCP — Security Best Practices (2025-06-18) — consent, confused-deputy risk, and the host-side controls that make fail-close defaults enforceable.
OWASP — LLM06: Excessive Agency — the blast-radius risk of handing an agent broad tool functionality and permissions without scoping.
OWASP — LLM01: Prompt Injection — why a model driving your tools is an untrusted caller, not just an inconvenient one.

I ran an MCP-gateway production-readiness audit on a popular open-source LLM gateway. Here's what it found.

Willian Pinho — Tue, 30 Jun 2026 20:41:45 +0000

I ran an MCP-gateway production-readiness audit on a popular open-source LLM gateway. Here's what it found.

Most teams wiring an LLM gateway to MCP tools ask one question: does it work? The harder question, the one that decides whether you sleep through the launch, is different. When the authorization check throws an unexpected exception, does the gateway deny the call or allow it? That single line of behavior separates a mature platform from an incident waiting for a quiet Tuesday.

So I built a structured way to answer it, and pointed it at a target that would not flatter the method.

The method, not the target

The audit is a read-only, evidence-backed review across seven dimensions: tool-access governance and RBAC, fail-close versus fail-open behavior, MCP and agent onboarding, observability and tracing, multi-LLM routing and cost controls, secrets and identity, and broader production-readiness. Every finding has to point at the specific code that justifies it, pinned to a commit, so the team can open the file and read the same lines I did. There's no live fault injection and no guesswork; every claim traces back to code at that revision. If a control is present in code but only takes effect when an operator turns it on, that gets recorded too, because the default is what ships to most deployments.

For a worked example, I used LiteLLM from BerriAI, pinned at a specific commit. It is a widely deployed open-source LLM proxy, the code is public, and it is the kind of mature project that would expose a sloppy methodology rather than a sloppy target. I want to be clear about the result up front: it scored well. Four green, three yellow, zero red across the seven dimensions. The verdict was "production-ready with caveats." This is a fair assessment of a capable platform, not a takedown. The interesting part is that even a strong gateway has edges a structured pass will surface, and those edges are exactly the things every team running MCP in production should check on their own deployment.

What it gets right

The dimensions that carry the most safety weight were the strongest.

Identity and secrets came back green with no significant gaps. There were no inline secret values in the configuration. Real config references the environment via os.environ and os.getenv, and the only sk- style strings in the tree were docstring examples. Identity is JWT and OIDC enforced on the actual gateway call path, not merely the dashboard login, and the end-user identity propagates through to MCP handling and spend logs instead of collapsing into one shared service credential. For MCP tokens, the gateway supports RFC 8693 OAuth token-exchange with audience and scope binding, so the MCP server receives a token minted for it rather than a forwarded user token. That follows the resource-server pattern the current MCP specification points at. One honest detail: it is an operator-enabled mode, not the default, so it counts as a control you have to turn on rather than one you inherit.

Observability was also green. OpenTelemetry is a first-class integration with dedicated GenAI semantic-convention mapping, so per-model token and cost attribution is possible rather than bolted on later. Inbound W3C traceparent headers are extracted through the standard propagator, which means end-to-end trace continuity is achievable across hops.

Routing and cost, the dimension LiteLLM is purpose-built for, held up. A declarative model_list maps virtual model names to physical deployments, and budget caps are genuinely enforced. An overrun raises a BudgetExceededError rather than firing an alert and letting the spend continue. Rate limits in requests and tokens per minute are expressible per key, per model, and even per MCP server. That is a real, enforced path against bill-shock and denial-of-wallet, not a dashboard that turns red after the money is already gone.

One honest caveat on observability: because this was a static review against a public repo with no live backend, I could not pull a real end-to-end trace and watch it reconstruct. The building blocks are present and standards-aligned. Confirming one real request stitched together end to end is a step any team should run against their own staging.

Three yellows worth checking on any deployment

None of these are missing controls. They are default-configuration and operational gaps, which is the typical profile of a capable platform that needs hardening rather than rearchitecture.

First, one fail-open line. Every per-level permission resolver fails closed: on an unexpected exception it logs and returns an empty set, which resolves to "no access" downstream. That is the correct posture. The exception is the top-level wrapper get_allowed_mcp_servers(), which returns the allow-all server set on an unexpected error instead of an empty list. The blast radius is bounded to servers an operator already marked as public, but fail-open in an authorization resolver is the single highest-risk class in the whole framework, because a degraded check silently becomes "allow." It is also a one-line fix plus a regression test, which gives it the best risk-reduction-per-effort in the audit.

Second, unpinned third-party MCP servers. The curated catalog launches stdio servers with floating commands like npx -y @sentry/mcp-server, with no version, digest, or checksum pin. That is a tampered-package away from a supply-chain incident, the class OWASP labels LLM03 in its 2025 list. Pinning by version and digest, and rejecting anything unpinned, closes it.

Third, per-tool least-privilege is opt-in. Authorization at the gateway is strong: it is enforced on caller identity as a strict intersection of key, team, end-user, agent, and org permissions, and the model is kept out of the authorization decision entirely, which is what defeats prompt-injection-to-tool-call. But absent a per-server allowed_tools allowlist, any caller with access to a server can invoke any tool on it, including write or external ones — the excessive-agency exposure OWASP tracks as LLM06. Making that allowlist required at onboarding, validated in CI, converts least-privilege from opt-in to default.

The lesson

A structured audit is not a search for a smoking gun. On a mature target there usually is not one, and there was not here. What the seven-dimension pass surfaced instead were the production-readiness edges that hide in a good codebase. One resolver that errs toward exposure where its siblings err toward safety. A supply chain that floats instead of pinning, and a least-privilege control that waits for someone to opt in. None of these show up when you ask "does it work," because the gateway works fine. They show up when you ask what happens at the boundaries, under error, and at the defaults most operators never change.

That is the value of the method. It turns "we think it's fine" into a scored picture with named fixes, effort estimates, and the exact code behind each finding, so the team is arguing about a specific line of behavior instead of a feeling.

The audit kit that produced this runs read-only and works in Claude Code, Cursor, or any MCP client. If you are putting an MCP gateway in front of production tools and want the same scored, evidence-backed pass on your own deployment, that is the scoped engagement I run.

Sources

LiteLLM (BerriAI), pinned commit 51ba6e39cd23576b9c2110361f1045782762f3e4 — the exact source audited; every finding points at code at this revision, so it can be read back at the same lines.
RFC 8693 — OAuth 2.0 Token Exchange — the token-exchange model behind audience- and scope-bound MCP tokens.
Model Context Protocol specification (2025-06-18) — the resource-server model the gateway's MCP token design follows.
OWASP Top 10 for LLM Applications (2025) — LLM03 (Supply Chain) and LLM06 (Excessive Agency) frame the unpinned-server and least-privilege findings.
W3C Trace Context — the traceparent propagation standard that enables end-to-end trace continuity.
OpenTelemetry GenAI semantic conventions — the per-model token and cost attribution mapping the gateway integrates.

Pre-mortem as plan debugger

Willian Pinho — Tue, 23 Jun 2026 17:11:55 +0000

The ritual most senior engineers skip

Everyone in this field has heard the word "pre-mortem." Almost nobody runs one as an actual habit.

The people who do ship cleaner work. The cost is small: about 10 minutes to generate the failure list, 25 to 30 for the whole ritual. What it buys you is avoiding the moment on a post-incident call where someone says "yeah, we knew this could happen and shipped anyway." Plenty of Sev-1s aren't preventable. For the ones that are, this is the cheapest way I know to catch them early.

What follows is the version I actually use: the mental flip that makes it work, the 10-minute structure, the three ways you can respond to each risk, and the cases where running a pre-mortem is just procrastination wearing a lab coat.

One thing to hold onto if you skip the rest: the useful work happens in past tense, before the incident, in concrete sentences.

Why risk registers do not work

A risk register is a passive list. It gets filed somewhere nobody opens, written in language nobody acts on.

It tells you "what could go wrong" without telling you what to do about any of it. And the entries are written in future-conditional, "might happen," "could cause," which your brain quietly files under low-probability, deal-with-it-later. You read the list, you feel covered, you did the responsible thing. You wrote the risks down.

The other problem is structural. The shipping plan and the register usually live in two different documents, so the register never forces anything back into the plan. It sits next to the work instead of changing it.

After a decade-plus of shipping, here's my honest read: most risk registers get filled in the afternoon before launch to satisfy a checkbox. Nobody who writes one believes in it, and nobody reads it afterward. Which is fine, because usually nobody reads it at all.

A pre-mortem has the opposite shape. It's active, it reads like a story, and it lives inside the plan.

The cognitive shift: past tense as forcing function

A pre-mortem is a story you write in the wrong direction. You write the post-incident retrospective before the incident, in past tense, with detail.

The past tense is what forces specificity. There's a study on prospective hindsight (Mitchell, Russo and Pennington, 1989) that found imagining an outcome has already happened produces roughly 25% more concrete reasoning than predicting it forward. That's the lever the pre-mortem pulls. It's also why "we missed the deadline" is useless and "row-level locks piled up under the signup spike and transactions queued past the 30-second timeout" is not.

Put the two side by side. The lazy version is "it broke." The useful version: the 30-second timeout cascaded into a 502 wall by minute three of the signup spike, conversion dropped 40% at peak hour because the payment provider rate-limited us, and the alerting system went quiet for 18 minutes because the alerting stack was its own alert sink.

The second version you can actually test. Every clause points at a specific failure mode you can prevent, shrink, or at least watch for.

This isn't pessimism dressed up. It's negative thinking pointed at the plan, run like a debugging session. You're not predicting the future. You're trying to break the document while it's still cheap to break.

I ran one last week on a SaaS I'm shipping. Ten failure modes in ten minutes. Ranked by impact times likelihood, the top three were the lock-contention story, the payment rate-limit story, and the silent-alerting story above. Each one got a countermeasure before ship. But the bigger payoff was sequencing: the pre-mortem killed two days of work, because writing down how the wrong order failed showed me a feature I'd put first should have been third. You only see the right sequence after you've described the wrong one falling over.

The 10-minute protocol

The "10 minutes" is the generation core, not the whole thing. Steps 1 and 2 eat the ten minutes; steps 3 through 5 add another 15 to 20. So the full ritual is closer to half an hour. Most teams stop after step 2, which is the whole reason pre-mortems get a reputation for not working. The discipline is in finishing.

The original method (Klein's) is a group exercise: five to ten minutes of imagined-failure writing, then you read them round-robin, no fixed count. What I describe below is an opinionated solo adaptation for ship-level calls. The thing I actually run on a Monday morning before a non-trivial deploy.

Solo, you only catch the failures you can already picture. So for anything launch-scale (new market, new product line, architecture you can't easily walk back), run it as a 30-minute group exercise with anonymous submission. That way the most junior person on the team can write down the failure mode the founder is too close to see. The brainstorming research is fairly brutal about face-to-face group ideation; anonymous parallel generation tends to beat it by 20 to 40%.

The five steps:

Set a timer for 10 minutes. The time-box is what stops you polishing.
Write 10 specific past-tense failure narratives. Concrete, not categories. Vendor outages, traffic shapes, a regulatory surprise, a key person out sick, a third-party API quietly changing its contract. Under 6 and you're still being abstract; over 12 and you're padding. Ten is the right squeeze for a 10-minute clock: one a minute, no editing.
Rank each one by impact times likelihood. Three buckets: ship-killing, recoverable, and acceptable.
The top 3 get countermeasures in the plan itself. Not in a separate doc. In the plan, as real tasks with an owner and a date.
The rest go in a deferred-risk file that you actually re-read at the next milestone.

The protocol is deliberately dumb. The hard part is running it before every ship that takes more than a day to roll back.

Countermeasure design: three patterns

For each of the top three, you pick exactly one response. Not two.

Eliminate

Change the plan so the failure mode can't happen. This is the most expensive option and the most durable. For the lock-contention case, what landed was moving primary-key allocation off a sequence and onto UUIDv7 on the signup-burst path, running READ COMMITTED. The failure mode doesn't get smaller. It's gone.

Attenuate

Shrink the blast radius for when it does happen. Cheaper, and partial. If the alerting stack can go dark, put an external uptime probe on a different vendor in a different region. The alerting system can still die; you just hear about it in 60 seconds instead of 30 minutes.

Instrument

Accept the failure mode but make sure you detect it in minutes, not hours. Cheapest of the three, and it leans entirely on someone being around to act on the signal. If you can't design the lock contention out before ship, then instrument lock-wait-time histograms and transaction-queue depth, alert on the 99th percentile, and accept that you'll respond in ten minutes rather than never having the bug.

There's a fourth pattern in the textbooks: transfer, meaning you push the risk onto a vendor SLA, insurance, or a contract clause. I leave it out on purpose. Mid-launch, transfer is usually not yours to pull; when it is, procurement moves in weeks, not inside a 10-minute loop. ISO 31000 and PMBOK keep it on the list. The version that survives contact with a Monday deploy doesn't.

Most launches end up using all three across their top-3 failures. The discipline is one pattern per failure. The moment you let yourself pick two, the countermeasure list bloats and the plan turns back into theater.

When NOT to run a pre-mortem

Skip it on low-stakes reversible stuff. A one-line PR, a typo, a copy tweak on an internal page. The ten minutes won't earn themselves back.

Skip it on calls you've already argued into the ground, where the choice is genuinely a coin flip. Running a pre-mortem on a coin flip is just a way to avoid deciding.

And skip it on anything you've already shipped. That's a post-mortem: a different ritual, with different head-space and different stakes.

The line I use: run a pre-mortem on anything that takes more than a day to roll back if it goes sideways. Under that bar, the ritual costs more than it saves.

One honest limit. A pre-mortem only reaches as far as your imagination. The real incident is very often the eleventh failure mode, the one nobody wrote down. Run them anyway; catching seven of eight ordinary failures still beats catching zero. Just don't let a complete-looking list trick you into thinking you've seen the whole risk picture.

Closing rule

If you can't describe how your next ship fails in 10 specific past-tense sentences, you haven't planned it. You've hoped. And hope has never held up under peak-hour traffic.

Sources

Klein, G. (2007). "Performing a Project Premortem." Harvard Business Review, September 2007 — https://hbr.org/2007/09/performing-a-project-premortem (canonical origin of the method)
Mitchell, D. J., Russo, J. E., & Pennington, N. (1989). "Back to the future: Temporal perspective in the explanation of events." Journal of Behavioral Decision Making, 2(1), 25-38 — https://doi.org/10.1002/bdm.3960020103 (empirical foundation for "past-tense forces specificity"; the prospective hindsight study)
Kahneman, D. (2011). Thinking, Fast and Slow. Chapter 24, on pre-mortem as antidote to optimism bias and planning fallacy
ISO 31000:2018 — Risk management guidelines — https://www.iso.org/standard/65694.html (canonical risk-treatment framework; eliminate/attenuate/instrument is an engineering simplification of clauses 6.5.2-6.5.3)
PMBOK Guide, 7th Edition (PMI, 2021) — https://www.pmi.org/standards/pmbok (alternative risk-response taxonomy: escalate / avoid / transfer / mitigate / accept)
Klein, G. (2009). Streetlights and Shadows: Searching for the Keys to Adaptive Decision Making. MIT Press — https://mitpress.mit.edu/9780262013390/streetlights-and-shadows/ (extended Klein corpus on naturalistic decision-making and pre-mortem limits)
Mullen, B., Johnson, C., & Salas, E. (1991). "Productivity loss in brainstorming groups: A meta-analytic integration." Basic and Applied Social Psychology, 12(1), 3-23 — https://doi.org/10.1207/s15324834basp1201_1 (why anonymous parallel generation outperforms face-to-face group brainstorming)
Bezos, J. — Type 1 vs Type 2 decisions, 2016 Amazon shareholder letter (restating the 2015 framing) — https://www.aboutamazon.com/news/company-news/2016-letter-to-shareholders (conceptual ancestor of the "one day to roll back" threshold)

The agent runtime event model

Willian Pinho — Fri, 19 Jun 2026 13:43:29 +0000

The framework wars are a distraction

Engineers keep asking me which agent framework to pick. LangChain or CrewAI or roll-your-own. It's the wrong question to lead with. The architectural choice that actually compounds isn't framework selection. It's where you can attach policy inside your agent runtime.

Every production agent stack I've shipped over the last eighteen months converged on the same answer: four runtime events, four policy-attachment surfaces, and the hook coverage at each event is what separates a demo from something a regulated buyer will sign for.

Here is the taxonomy, the bug class each event prevents, and a three-question audit you can run on any agent stack this week.

What an event model is

Every production agent runtime worth shipping exposes a small set of policy-attachment events. The taxonomy below comes from Claude Code's hook model, a developer-side agent runtime I work in daily: UserPromptSubmit, PreToolUse, PostToolUse, Stop. I've adopted the same four-event model in the server-side agent stack my SaaS runs, mapped onto its runtime. The names are Claude Code's; the architectural pattern is what's portable. LangChain calls the analogous surfaces on_chat_model_start / on_tool_start / on_tool_end / on_agent_finish; OpenAI's Agents SDK calls them on_agent_start / on_tool_start / on_tool_end / on_agent_end. The names differ. The attachment surfaces, and the bugs they prevent, are the same.

UserPromptSubmit — before the prompt reaches the model.
PreToolUse — before the agent's chosen tool fires.
PostToolUse — after the tool returns, before the model sees the output.
Stop — after the agent says "done".

Each event is a policy-attachment surface with its own semantics, and the differences are what you design around. The latency budget varies: UserPromptSubmit must run in single-digit milliseconds because it sits on the user's input path, while Stop can take a full second because the user has already submitted and is reading. That gap is why the input-path events can't run a synchronous deep check — you fail fast there and save the real verification for Stop, where you can afford it. The failure modes differ too when a hook blocks. So does the data shape: the prompt event sees raw user text, the pre-tool event sees the planned tool invocation, the post-tool event sees the tool's return payload, and the stop event sees the full transcript.

The architectural question isn't "which framework". It's "which of these four events does my runtime actually expose, and what policy coverage do I have at each one?".

It sits closer to an aspect-oriented interceptor than to Express middleware, though neither maps cleanly. Middleware composes around a fixed request-response shape; an AOP interceptor wraps one method call. A hook attaches at a named lifecycle event defined by the runtime, the runtime's dispatcher decides when and whether you fire, the payload shape is event-specific, and your only contract is exit code and mutated payload.

One thing the framework cannot decide for you: what happens when the hook itself crashes. PII redactors and secret-leak blockers must fail closed, better a denied request than a leaked credential. Completeness verifiers should fail open when they gate a plain response, a crashed classifier should not block the user from getting one. The exception proves the rule: when "done" gates a destructive action like a migration or a deploy, fail closed and alert instead. The hook's failure mode is policy, not infrastructure. Get this wrong and you ship either a security hole or a denial-of-service.

What class of bug each event prevents

UserPromptSubmit

This event hard-blocks secrets in prompts using pattern matching plus entropy scoring for unknown formats, with provider verification on the high-value patterns (Stripe, AWS, GitHub) when latency budget allows. A canary token seeded in your secret stores catches the rare leak that slips both: if that token ever shows up in a submitted prompt, a real credential took the same path. It tokenizes PII into reversible placeholders so the model reasons over ⟪PII_email_42⟫ instead of the real address. The receipt: a class of credential leak that slipped past code review three times in one week on a SaaS I'm shipping stopped being possible once this was wired in. The hook returns exit 2 and the prompt never reaches the provider. Same leak, caught at the runtime instead of in a review someone has to remember to do.

PreToolUse

Cost-budget enforcement at tool-call granularity: per-day, per-task, per-tool. Blocklist enforcement on file reads (no .env*, no credential files, no rendered config with secrets baked in). Tool whitelisting in adversarial or untrusted-input contexts. This is the event that turns "the agent can do anything" into "the agent can do what its policy allows". One caveat worth stating plainly: this is a policy boundary, not an isolation boundary. For genuinely untrusted code execution you still want OS-level sandboxing (gVisor, Firecracker) underneath — the hook decides what's allowed, the sandbox contains what goes wrong.

PostToolUse

PII redaction on stdout before the model ingests the tool output. A compliance audit log with a hash chain you can hand to a security reviewer. Injection-scan: tool outputs that look like prompt injections get stripped before they re-enter the conversation, which closes a class of indirect prompt injection that pure system-prompt defense cannot reach.

Stop

Completeness verification. A small classifier reads the user's items and asks whether each one got addressed. In our deployment, after about two weeks of tuning, the false-positive rate settled near 8% — so we treat it as a soft warning, not a hard block. The math is forgiving: a small classifier runs at roughly $0.001/turn (Haiku pricing, ~500 input tokens), so catching even one in twenty "I'll do that next" slop patterns covers the cost many times over. Test re-run gating also lives here, before the agent declares done.

Why this beats framework selection

Hooks are framework-agnostic. The contract is the runtime event, not the framework API. Swap one framework for another and the policy logic you wired in still applies — you rewrite the thin integration glue that extracts each runtime's payload, not the policies themselves. That's a fraction of a full re-architecture.

The economic argument is sharper. Framework choice is a decision you'll revisit as the ecosystem churns — new entrants, better abstractions, a migration every couple of years. Hook coverage outlives all of that, because the four events stay put even as the policies you attach to them keep growing.

OWASP's first LLM Top 10 in 2023 already flagged this, and the 2025 update sharpened it. Four of the ten items — Prompt Injection (LLM01), Sensitive Information Disclosure (LLM02), Improper Output Handling (LLM05), Excessive Agency (LLM06) — are runtime-control problems. None of them is a framework-selection problem. The conversation moved one layer down, to where you can actually attach policy.

A three-question audit

Three questions for any production agent stack:

Which event does your secret-leak prevention attach to? If none, you are shipping with a known leak surface every team has crossed at least once. (OWASP LLM02: Sensitive Information Disclosure.)
Which event catches completion lies, agent says done when it is not? If none, user trust erodes invisibly until churn spikes and you cannot trace why. (No OWASP entry yet. This is the gap the standard has not caught up to.)
Which event audits tool outputs for PII before the model reingests them? If none, regulated industries cannot deploy your stack regardless of how impressive the demo is. (OWASP LLM02 + LLM05: Improper Output Handling.)

Frameworks are a commodity. Your hook coverage is the moat.

Sources

Claude Code Hooks reference — https://code.claude.com/docs/en/hooks (authoritative event surface, payload shape, exit-code semantics)
LangChain Callbacks (BaseCallbackHandler) — https://reference.langchain.com/python/langchain-core (cross-framework mapping)
OWASP Top 10 for LLM Applications 2025 — https://genai.owasp.org/llm-top-10/ (LLM01 / LLM02 / LLM05 / LLM06 mapping to runtime events)
NIST AI Risk Management Framework — https://www.nist.gov/itl/ai-risk-management-framework (the Generative AI Profile, NIST-AI-600-1, July 2024 — its govern/map/measure/manage functions sit at the organizational and lifecycle level; these runtime events are one place those controls get operationalized, not where NIST defines them)
Microsoft Presidio — Anonymizer — https://microsoft.github.io/presidio/anonymizer/ (reversible PII tokenization pattern)
Trufflehog — verifier-based secret detection — https://github.com/trufflesecurity/trufflehog (2026 industry standard for credential scanning)
Greshake et al., "Not what you've signed up for: Compromising Real-World LLM-Integrated Applications with Indirect Prompt Injection" — https://arxiv.org/abs/2302.12173 (academic foundation for the PostToolUse injection-scan claim)
Anthropic Claude pricing — https://platform.claude.com/docs/en/about-claude/pricing (verifies the ~$0.001/turn cost number)

I made Claude, GPT and Gemini predict the entire 2026 World Cup. Here's the experiment design.

Willian Pinho — Thu, 11 Jun 2026 17:53:13 +0000

The 2026 World Cup kicks off today: 48 teams, 104 matches, five weeks. I'm using it as a benchmark.

Three frontier models (Claude Opus 4.8, GPT-5.2 and Gemini 3.1 Pro) predicted every group match with scorelines and win/draw/loss probabilities, then a complete knockout bracket down to the champion and Golden Boot. Every prediction was locked before kickoff and committed to a public repo. As real results arrive, a live site scores them automatically.

Building it surfaced some genuinely weird model behavior. GPT-5.2, for instance, kept inventing an impossible football rule until the prompt explicitly forbade it. More on that below.

But the core of the project is the experiment design: the picks matter less than how the question was asked.

The confound nobody controls for

Ask an LLM with web access to predict a match and you have no idea what you measured. You can't tell whether it reasoned from internal knowledge, scraped a reliable source, or hallucinated a plausible-sounding stat. Two models citing different injury reports aren't comparable. A friend reviewing the project put it bluntly: without a standardized source, the models can just make that information up.

So each model runs under three conditions:

Arm	Setup	What it isolates
web	Chat/CLI with live web access	Model + free-form sourcing (uncontrolled)
baseline	API, no tools, no extra context	Pure parametric knowledge
enriched	API, no tools, + identical data snapshot	Reasoning over controlled inputs

The enriched snapshot is the same for all three models: the official FIFA ranking (April 2026 release, pulled from FIFA's own API) and World Football Elo Ratings for all 48 teams, versioned in the repo with sources and retrieval dates. No model gets an information advantage.

If enriched beats baseline, the value was in the data. If baseline holds its own, the knowledge was already in the weights. The web arm tells us whether free browsing helps or just adds noise.

Keeping the no-tools arms honest

"No tools" is an instruction until you verify it. The API arms run through a LiteLLM gateway with no tool definitions. Gemini's runs go through its CLI, which reports per-call tool stats, and the runner rejects any response where the tool-call counter isn't zero (same pattern for Claude's bracket runs, with all tools disallowed). It's verified per request, not assumed:

const { content, totalTokens, toolCalls } = await send(prompt);
if (opts.requireNoTools && (toolCalls ?? 0) > 0) {
  // Arm violation, not a model error: the no-tools condition must hold. Retry raw.
  if (attempt === MAX_RETRIES) {
    fail(
      `Group ${gf.group}: transport used ${toolCalls} tool call(s) — no-tools arm violated`,
    );
  }
  continue;
}

Outputs are strict JSON, validated with Zod against the official fixture list — every response must contain exactly the six expected team pairs for its group:

const PredictionItem = z.object({
  teamA: z.string().min(1),
  teamB: z.string().min(1),
  scoreA: z.number().int().min(0).max(30),
  scoreB: z.number().int().min(0).max(30),
  probWinA: z.number().min(0).max(100).optional(),
  probDraw: z.number().min(0).max(100).optional(),
  probWinB: z.number().min(0).max(100).optional(),
});

Invalid responses get the validation errors fed back, up to three attempts.

Now, the weird behavior I promised. GPT-5.2 consistently labeled knockout ties that were level after extra time as "decided in extra time", which is impossible under the rules, and validation feedback alone didn't fix it. It only stopped when the prompt spelled out: a level score after 120 minutes means penalties. Claude had its own quirk: the schema documented the winner field as "winner": "<teamA|teamB>", and it returned the literal string "teamA". Prompt precision beats prompt length.

What they predicted

The headline disagreement:

Claude picks Spain as champion in all three arms (the only model that's consistent with itself).
Gemini says Brazil (web and baseline) but switches to France when given the standardized data.
GPT-5.2 says Brazil on the web arm, France on both API arms.

All three picked Mbappé for the Golden Boot in 7 of the 9 brackets.

That inconsistency across arms is itself a result: the same model gives a different answer depending on what information it was handed. The tournament will tell us which configuration was actually calibrated.

Scoring

Group stage, per match: 5 points for the exact score, 3 for the correct result plus one exact side, 2 for the result only. On top of that, a multiclass Brier score over the win/draw/loss probabilities, which heavily penalizes overconfident wrong predictions. That matters more to me than raw hit rate.

Brackets are scored pool-style: 1/2/4/8/16 points per team correctly placed in the real round of 32, 16, quarters, semis and final, plus 32 for the champion. Max 192.

Honest limitations

The API arms receive the fixture list (the web arm had to recall the official draw), so they test judgement on outcomes, not memory of the schedule.
Group tiebreakers are simplified; fair-play points can't be reproduced from scorelines.
Player-level predictions (scorers, cards) are out of scope: adding them after kickoff would break the locked-before-the-tournament guarantee.
One tournament is one sample. This measures calibration on a single event, not "which model is smarter."

Stack, briefly

Next.js 16 (App Router) + Prisma 7 + SQLite, results sync from openfootball every 30 minutes, 56 unit tests on the pure scoring/standings/validation logic. The real bracket renders with official placeholder slots ("Group A runner-up", "Winner of match 73") and fills itself in as the tournament progresses.

Everything — prompts, raw model JSON, dataset, runner scripts, scoring code — is in the repo. If you think the methodology is flawed, the receipts are right there to prove it.

Live leaderboard: https://worldcup2026.willianpinho.com
Repo: https://github.com/willianpinho/worldcup-predictor-2026

I'll publish the group-stage verdict on 28 June and a full post-mortem after the final on 19 July. Place your (intellectual) bets now: does the model that knows the most football win, or the one that's best calibrated about what it doesn't know?

Independent project — not affiliated with Anthropic, Google or OpenAI. Educational experiment, not betting advice.

I wrote a read-only scanner for MCP / agent-gateway production-readiness

Willian Pinho — Tue, 09 Jun 2026 23:20:10 +0000

I build and maintain an MCP server that works in Claude Code, Cursor, and Gemini CLI. Doing that for a while taught me something uncomfortable: the distance between a registered MCP server and full access to everything it exposes is roughly zero. The convenience is the exposure.

So when teams move an agent from "works in the demo" to "touches real systems," the same gaps show up every time. Tool access gets granted per-server instead of per-operation. Fail-open becomes the default nobody chose on purpose. New servers show up by editing a config and restarting — no review gate, no pinned versions. Often nothing traces a call across agent → gateway → model → tool, and multi-model usage runs with no routing policy, which becomes a surprise bill at the end of the month.

Most of that is visible by reading the repo. I got tired of reading it by hand, so I wrote mcp-gateway-scan.

What it checks

It's a static, read-only scan across seven dimensions:

Tool-access / RBAC — are tools scoped per-operation against an identity, or does registering a server hand over its whole surface?
Fail-close — when a model, gateway, or tool dependency degrades, does the system refuse safely or improvise?
Onboarding / supply-chain pinning — is adding a server a reviewed, declarative change with pinned versions, or a config edit and a restart?
Observability / OTel — is there end-to-end tracing you can reconstruct a call from?
Multi-LLM routing & cost — is there a routing policy, fallback behavior, and per-team cost attribution, or one hardcoded model and hope?
Secrets / identity — credentials in configs vs. references; is identity propagated to tool calls?
Production-readiness — kill-switch, rate limits, eval gates, the operational table stakes.

It's read-only by design. It never executes your code and never prints a secret value. At most it points to a secret literal sitting inline in a config it shouldn't be — a location to check, not a verdict.

The seven dimensions track failure modes the official MCP security guidance and the OWASP LLM Top 10 call out — over-broad tool access, fail-open agency, and unpinned supply chains among them (MCP security best practices, OWASP LLM Top 10).

Three ways to run it

CLI, for a one-off read:

npx mcp-gateway-scan ./your-repo

CI gate, exits non-zero on any red:

npx mcp-gateway-scan --ci ./your-repo

MCP server, so your agent can scan on request:

claude mcp add gateway-scan -- npx -y mcp-gateway-scan mcp

Then ask Claude or Cursor "scan my gateway" and the agent calls the tool itself. The thing that scans agent stacks is, fittingly, an agent tool.

What the output looks like

mcp-gateway-scan ./your-repo

  Tool-access / RBAC ............ yellow  tools registered per-server; no per-operation grants
  Fail-close .................... red     no fallback policy; gateway errors return last cached response
  Onboarding / supply-chain ..... green   declarative config, versions pinned
  Observability / OTel .......... yellow  request logging present; no trace propagation to tool calls
  Multi-LLM routing & cost ...... green   routing policy + per-team attribution found
  Secrets / identity ............ red     API key inline in gateway.config.json
  Production-readiness .......... yellow  rate limits present; no kill-switch

  2 red · 3 yellow · 2 green

Reds are the ones I'd fix before the next deploy. Yellows are "you have the foundation, it's not wired through." Greens mean the pattern is actually in place, not just intended.

Wiring the CI gate

For most teams, the --ci flag is where this earns its keep. Drop it in a workflow and a new red blocks the merge:

- name: Gateway readiness gate
  run: npx mcp-gateway-scan --ci ${{ github.workspace }}

Non-zero exit on red, zero otherwise. You can ratchet: ship today with yellows allowed, then tighten the gate to fail on yellow once you've cleared the reds. The scanner is fast and has no network dependency, so it's cheap to run on every PR.

What it doesn't do

It's a first read, not a verdict. A static scan can tell you there's no fallback policy in the config; it can't tell you whether your fail-close behavior actually holds under load, because that needs fault injection against a running system. It reads what you declared, not what happens at 3 a.m. when a provider rate-limits you.

For calibration I took the seven-dimension methodology to LiteLLM, a mature and widely-deployed proxy, pinned at a commit. It came back 4 green / 3 yellow / 0 red — production-ready, with the usual edges a structured pass surfaces in a good codebase: one authorization resolver that fails open where its siblings fail closed, unpinned third-party MCP servers, and per-tool least-privilege left opt-in. Then I built a deliberately-broken reference gateway that fails the same checks by construction. The scanner here automates the static slice of that methodology — the part you can run in seconds, before any deeper review.

Try it

Run it: npx mcp-gateway-scan ./your-repo — MIT, github.com/willianpinho/mcp-gateway-scan
npm: mcp-gateway-scan

If you want the deeper version, I run a full Provenwright MCP Gateway Readiness Audit (live fault-injection, trace verification, a 90-day remediation roadmap) at willianpinho.com/mcp-audit. The free scanner stands on its own; that's just there if you want the rest.

Large File MCP: Handle Massive Files in Claude with Intelligent Chunking

Willian Pinho — Tue, 11 Nov 2025 03:58:03 +0000

@ -0,0 +1,325 @@

Large File MCP: Handle Massive Files in Claude with Intelligent Chunking

Have you ever tried to analyze a 500MB log file with Claude only to hit token limits? Or struggled to navigate through a massive CSV dataset? I built Large File MCP to solve exactly these problems.

The Problem with Large Files in AI Assistants

AI assistants like Claude Desktop are incredibly powerful, but they have a fundamental limitation: token context windows. When you're dealing with:

Multi-gigabyte log files from production servers
Large CSV datasets with millions of rows
Massive JSON configuration files
Extensive codebases spanning thousands of lines

...traditional file reading approaches fail. You can't just load everything into memory, and manually chunking files is tedious and error-prone.

Introducing Large File MCP

Large File MCP is a Model Context Protocol (MCP) server that provides intelligent, production-ready large file handling for AI assistants. It's designed to make working with files of any size as seamless as working with small text files.

Key Features

Smart Chunking
The server automatically detects your file type and applies optimal chunking strategies:

Text/log files: 500 lines per chunk
Code files (.ts, .py, .java): 300 lines per chunk
CSV files: 1000 lines per chunk
JSON files: 100 lines per chunk

Intelligent Navigation
Jump to any line in a file with surrounding context:

Show me line 1234 of /var/log/system.log with context

Powerful Search
Find patterns with regex support and contextual results:

Find all ERROR messages in /var/log/app.log

Memory Efficient
Files are streamed line-by-line, never fully loaded into memory. Built-in LRU caching provides 80-90% hit rates for frequently accessed files.

Production Ready

91.8% test coverage
Cross-platform (Windows, macOS, Linux)
Type-safe TypeScript implementation
Comprehensive documentation

Installation

Installing Large File MCP is straightforward. Choose your preferred method:

Claude Desktop (Recommended)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "large-file": {
      "command": "npx",
      "args": ["-y", "@willianpinho/large-file-mcp"]
    }
  }
}

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after editing.

Claude Code CLI

# Add globally for all projects
claude mcp add --transport stdio --scope user large-file-mcp -- npx -y @willianpinho/large-file-mcp

# Verify installation
claude mcp list

npm Global Install

npm install -g @willianpinho/large-file-mcp

Real-World Use Cases

Let me show you how Large File MCP transforms common workflows:

1. Analyzing Production Logs

Scenario: You need to debug a production issue buried in a 2GB nginx log file.

With Large File MCP:

Find all 500 errors in /var/log/nginx/access.log from the last hour

The AI assistant will:

Use search_in_large_file with regex pattern
Return matching lines with context
Stream results efficiently without loading the entire file

Result: Found 47 errors in ~3 seconds, with full context for each match.

2. Code Navigation in Large Codebases

Scenario: Understanding function definitions in a 10,000-line Python file.

With Large File MCP:

Find all class definitions in /project/src/main.py and explain their purpose

The server uses intelligent chunking to:

Navigate to each class definition
Provide surrounding context
Cache frequently accessed code sections

Result: Instant navigation to any part of the codebase with full context.

3. CSV Data Exploration

Scenario: Analyzing a 500MB sales dataset with 5 million rows.

With Large File MCP:

Show me the structure of /data/sales.csv and find all transactions over $10,000

The AI uses:

get_file_structure - Get metadata and sample rows
search_in_large_file - Find high-value transactions
Smart chunking - Process 1000 rows at a time

Result: Comprehensive analysis without loading 500MB into memory.

4. Streaming Very Large Files

Scenario: Processing a 5GB JSON dataset that exceeds memory limits.

With Large File MCP:

Stream the first 100MB of /data/huge_dataset.json

Uses stream_large_file with:

Configurable chunk sizes (default 64KB)
Starting offset support
Maximum chunk limits

Result: Progressive processing of massive files with minimal memory footprint.

Available Tools

Large File MCP provides 6 powerful tools:

1. read_large_file_chunk

Read specific chunks with intelligent sizing:

{
  "filePath": "/var/log/system.log",
  "chunkIndex": 0,
  "includeLineNumbers": true
}

2. search_in_large_file

Regex search with context:

{
  "filePath": "/var/log/error.log",
  "pattern": "ERROR.*database",
  "regex": true,
  "contextBefore": 2,
  "contextAfter": 2
}

3. navigate_to_line

Jump to specific lines:

{
  "filePath": "/code/app.ts",
  "lineNumber": 1234,
  "contextLines": 5
}

4. get_file_structure

Comprehensive file analysis:

{
  "filePath": "/data/sales.csv"
}

5. get_file_summary

Statistical summary:

{
  "filePath": "/data/report.txt"
}

6. stream_large_file

Stream files progressively:

{
  "filePath": "/data/huge_file.json",
  "chunkSize": 65536,
  "maxChunks": 10
}

Performance Benchmarks

Here's how Large File MCP performs across different file sizes:

File Size	Operation Time	Method
< 1MB	< 100ms	Direct read
1-100MB	< 500ms	Streaming
100MB-1GB	1-3s	Streaming + cache
> 1GB	Progressive	AsyncGenerator

Caching Performance:

LRU Cache: 100MB default size
TTL: 5 minutes
Cache hit rate: 80-90% for repeated access
Significant speedup for frequently accessed files

Configuration & Customization

Fine-tune behavior using environment variables:

{
  "mcpServers": {
    "large-file": {
      "command": "npx",
      "args": ["-y", "@willianpinho/large-file-mcp"],
      "env": {
        "CHUNK_SIZE": "1000",
        "CACHE_ENABLED": "true",
        "CACHE_SIZE": "209715200",
        "MAX_FILE_SIZE": "10737418240"
      }
    }
  }
}

Available Options:

Variable	Description	Default
`CHUNK_SIZE`	Lines per chunk	500
`OVERLAP_LINES`	Chunk overlap	10
`MAX_FILE_SIZE`	Max file size	10GB
`CACHE_SIZE`	Cache size	100MB
`CACHE_TTL`	Cache TTL	5min

Why MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how AI assistants interact with external tools and data sources. Benefits include:

Universal Compatibility: Works with Claude Desktop, Claude Code CLI, and other MCP-compatible clients
Security: Sandboxed execution with explicit permissions
Extensibility: Easy to integrate with other MCP servers
Standardization: One implementation works everywhere

Production-Ready Quality

Large File MCP is built to production standards:

91.8% Test Coverage - Comprehensive test suite with Jest
Type Safety - Written in TypeScript with strict typing
CI/CD - Automated testing and deployment
Documentation - Complete docs at willianpinho.github.io/large-file-mcp
Active Maintenance - Regular updates and bug fixes

Getting Started

Ready to handle large files effortlessly?

Install the server:

   claude mcp add --transport stdio --scope user large-file-mcp -- npx -y @willianpinho/large-file-mcp

Verify installation:

   claude mcp list

Start using it: Open Claude and try:

   Analyze /var/log/system.log and find all errors

Links & Resources

GitHub: github.com/willianpinho/large-file-mcp
npm: npmjs.com/package/@willianpinho/large-file-mcp
Documentation: willianpinho.github.io/large-file-mcp
Issues: github.com/willianpinho/large-file-mcp/issues

Conclusion

Large File MCP transforms how you work with massive files in AI assistants. Whether you're debugging production logs, analyzing datasets, or navigating large codebases, intelligent chunking and streaming make it seamless.

The combination of smart chunking, powerful search, efficient caching, and production-ready quality makes it an essential tool for developers working with large files.

Give it a try and let me know what you think! Star the project on GitHub if you find it useful.

What large file challenges are you facing? Share your use cases in the comments!