The Zod trap: Why your AI agent is breaking MCPFusion architecture

I was reviewing an agent's recent output for a new MCP server implementation, and at first glance, it looked perfect. The TypeScript was clean, the types were explicit, and the logic followed the requirement to list users from a database.

Then I actually looked at how it defined the schema. It used z.object().

If you're using MCPFusion, that's an immediate failure. It doesn't matter if the code 'works' in a vacuum; it violates the entire architectural contract we built to make these agents production-ready. This is a growing problem: LLMs are incredibly good at writing code, but they are remarkably bad at following frameworks they weren't explicitly trained on. They fall back to their strongest training data—standard Zod schemas and flat JSON responses—and in doing so, they quietly strip away the security and governance layers that make MCPFusion useful.

The Illusion of Working Code

When an LLM writes a tool using z.object(), it's essentially bypassing every safeguard in the defineModel() ecosystem. In MCPFusion, we don't just want to know what a User looks like; we need to know which fields are sensitive.

Using raw Zod means you lose .hidden(). You lose m.fillable(). You lose the ability for the engine to automatically resolve .toApi() aliases. If an agent sends a password_hash through a tool that used a raw schema, and there's no Presenter layer enforcing egress rules, that hash is now part of your context window. It's out in the wild.

This isn't just about being pedantic about folder structures or 'clean code.' This is about preventing data leaks and ensuring that when an agent performs a f.query(), it's actually performing a safe, cacheable read operation.

The Semantic Mismatch

Another pattern I keep seeing—and this one drives me crazy—is the misuse of semantic verbs. LLMs treat all tool executions as generic 'functions.' They see an endpoint that fetches logs and they think f.mutation() because it's hitting a database.

In MCPFusion, if you use f.mutation() for a read operation, you've just broken the agent's ability to optimize. f.query() tells the engine: 'This is safe/idempotent; we can cache this and retry it.' f.mutation() says: 'Stop everything, this is destructive, ask the user for permission.'

When an LLM defaults to f.action() or f.mutation() because it doesn't understand the side-effect implications of your specific framework, you end up with an agent that is either dangerously over-privileged or frustratingly hesitant.

Teaching via Rejection

This is exactly why I built the MCPFusion Developer Prover.

I realized that documentation isn't enough. You can feed an LLM a 50-page README, but as soon as it starts generating code, its internal weights for 'Standard Zod Pattern' will overpower the context you provided. It needs more than suggestion; it needs structured reflection.

The Prover doesn't write the code for the agent. Instead, it acts as an architectural gatekeeper. Every time the agent attempts to implement a tool or a model, the Prover validates it against five specific decision pivots:

1. mvaRespected: Is there actual separation between Model, Presenter, and Tool logic?
2. modelUsed: Are we using defineModel() with proper casts? Or are we backsliding into raw z.object()?
3. presenterAttached: Does every data-returning tool have a .returns(Presenter) call to handle egress validation?
4. semanticVerbCorrect: Is the agent using f.query for reads and f.mutation for writes?
5. fileStructureCorrect: Are we polluting the tool file with model definitions?

When the agent fails, the Prover doesn't just say 'Error.' It provides a verdict—like RAW_SCHEMA_DETECTED or SEMANTIC_VERB_WRONG—and explains exactly what was lost (e.g., the loss of m.hidden() or .toApi()). This forces the agent into a loop of structured learning. It turns every mistake into a micro-lesson in MVA architecture.

Why this matters for production

If you're building hobbyist MCP servers, sure, use raw Zod. Use whatever works. But if you are building tools that connect to Salesforce, WhatsApp Business, or internal company databases via Vinkius, the 'standard' way of coding is your enemy.

You need the MVA (Model-View-Agent) contract to be enforced at the code level so that your governance policies—DLP, SSRF prevention, and audit chains—actually have something to hook into.

You can find the Developer Prover in our MCP catalog on Vinkius. If you're tired of debugging why your agent is leaking sensitive fields or why its 'read-only' tools are triggering confirmation prompts, it might be worth integrating this into your development pipeline.

MCPs are the music of AI Agents. We built the catalog. Discover Vinkius MCP Catalog.