Why Your AI Keeps Getting It Wrong: A Parable About MCP and the Source of Truth

This is a made-up story. No payments architects were harmed in the writing of this blog post. But the problem it describes? Very, very real.

Meet Jane. She's a meticulous payments architect at a growing company. She designed "NexusPay"—a custom payment gateway—and did something rare: she wrote pristine documentation. Clear authentication flows. Required fields clearly marked. Error codes with explanations. Example calls that actually worked.

Jane was proud of her docs. They were the single source of truth for how payments should work.

There was just one problem. Nobody was reading them.

The Irony of Good Documentation

Jane's developers weren't lazy. They were busy. And like developers everywhere, they'd discovered a productivity hack: AI coding assistants.

When a frontend developer needed to implement a new refund feature, they'd open their IDE and type: "Write a React hook to process a refund with NexusPay."

The AI would dutifully generate code. The developer would paste it. And then... it would fail.

Not dramatically. Not obviously. But subtly wrong in ways that took hours to debug:

• The AI used an endpoint version deprecated last year (
  code

  Copy

  /v1/refund

  instead of
  code

  Copy

  /v2/payments/refunds

  ).
• It handled errors by parsing string messages, ignoring the structured error codes Jane had carefully defined.
• It included a "rememberMe" flag for saving payment details—a feature removed months ago for security compliance.

The code looked right. It felt right. But it was wrong.

Jane would get frustrated. "The documentation is right there!" she'd say. "Why doesn't anyone just read it?"

But here's the thing: the developers weren't the ones writing the code. The AI was. And the AI couldn't read Jane's docs.

The Root Problem: Where Do AIs Get Their Answers?

This is the critical insight that changes everything: AI assistants don't know anything. They guess.

When you ask an AI to write code, it's not looking up the answer in a manual. It's pattern-matching across its training data—millions of public repositories, Stack Overflow posts, tutorials, and forum threads. It's generating the statistically most likely code based on everything it's ever seen.

And what's the average quality of payment integration code on the internet? Not great. Outdated practices. Deprecated endpoints. Workarounds from 2018 that became cargo-culted best practices.

The AI wasn't being malicious. It was doing exactly what it was trained to do. It just had no way of knowing that Jane's docs existed.

Enter Sakhile

Jane shared her frustration with her colleague Sakhile, a senior engineer who'd been reading about something called the Model Context Protocol.

"Ah," Sakhile said, "you need an MCP."

Jane was confused. "An MCP? I need them to read, not more protocols!"

Sakhile smiled. "An MCP—Model Context Protocol—is exactly what will make the AI 'read' your docs."

What Is MCP? (The Non-Technical Version)

Model Context Protocol (MCP) is an open standard that connects AI assistants directly to your data.

Think of it this way: normally, when you ask an AI a question, it's like asking someone who's read thousands of books but hasn't looked at a newspaper in two years. They know a lot, but they don't know what happened yesterday. And they definitely don't know about your company's internal docs.

MCP is like handing that person a tablet connected to your company wiki, your API documentation, and your database. Now when you ask a question, they can check the tablet before answering.

It's a universal adapter for AI context. Just as USB-C lets you plug one cable into many different devices, MCP lets AIs plug into many different data sources—your docs, your APIs, your codebase.

The MCP Server: Making Jane's Docs Accessible

Sakhile built a simple MCP server. It wasn't complicated. It just connected to three things:

1. Jane's OpenAPI specification (the machine-readable version of her docs)
2. The internal documentation wiki (where Jane's detailed guides lived)
3. The company's TypeScript type definitions (the exact types used in production)

The MCP server didn't do anything fancy. It just made these sources available in a standardized way that any MCP-compatible AI could query.

Before and After MCP

Let's look at what changed.

Before MCP:

Developer types: "Write code to refund a transaction on NexusPay."

AI thinks: "I've seen 10,000 examples of payment refunds in my training data. The most common pattern involves calling a

/refund

Result: Code that works in a generic sense but fails for NexusPay specifically. Hours of debugging ahead.

After MCP:

Developer types: "Write code to refund a transaction on NexusPay."

AI thinks: "I notice the user has access to the 'NexusPay API' MCP server. Let me query it for the correct information."

MCP server responds: "Here's the current OpenAPI schema for refunds. The endpoint is

/v2/payments/refunds

transactionId

reason

reason

AI generates code using exactly this information.

Developer gets working code on the first try.

Why This Story Matters (Even Though It's Made Up)

I made up Jane and Sakhile. NexusPay isn't real. But the dynamic here plays out in every organization that uses AI-assisted development:

• You have documentation.
• Your developers use AI.
• The AI can't read your docs.
• The AI generates wrong code.
• Everyone gets frustrated.

This isn't a failure of the AI. It's a failure of context. The AI is working with the information it has. It just doesn't have access to the right information.

MCP solves this by creating a bridge. Your docs stay where they are. The AI stays where it is. But now they can talk to each other.

What MCP Actually Does

To be slightly more technical for a moment:

MCP creates a standardized way for AI applications to discover and query tools and data sources. An MCP server exposes capabilities—like "search documentation" or "get API schema"—that any MCP client can use.

In practice, this means:

• Your OpenAPI spec becomes something an AI can query directly.
• Your internal wikis become searchable by an AI assistant.
• Your database schemas become accessible for query generation.
• Your codebase becomes referenceable for refactoring tasks.

The AI doesn't need to have been trained on your specific information. It just needs to know how to ask for it.

The Broader Point: AIs Need Sources of Truth

The core insight from this little parable is simple but profound:

AIs are only as good as their sources.

Right now, most AIs rely on their training data—a static snapshot of the internet from some point in the past. That's useful for general knowledge, but it's terrible for anything specific, current, or proprietary.

MCP is part of a broader shift toward making AIs retrieval-augmented—giving them the ability to fetch fresh, relevant information at query time instead of relying solely on what they memorized during training.

For organizations, this means:

• Your documentation becomes an asset that AI can actually use
• Your internal standards actually get followed in AI-generated code
• Your developers spend less time debugging and more time building
• Your institutional knowledge stops being trapped in wikis nobody reads

The Punchline

Back to our story: Sakhile's MCP server took an afternoon to build. Jane didn't have to change her documentation. The developers didn't have to change their workflow. The AI just... started getting it right.

Jane's docs finally became what she always wanted them to be: the source of truth, actually used.

That's the promise of MCP. Not more protocols. Not more work. Just a bridge between the information you already have and the AIs your team already uses.

This story is fictional. The problem is not. If you're dealing with AI hallucinations in your development workflow, MCP might be worth a look.

Want to learn more? Check out the Model Context Protocol documentation or see how tools like Claude Desktop and Continue.dev are starting to implement MCP support.