infrastructureL1 Ad-hocMCP & Tool Integration

Agent knows only public API knowledge

When an agent operates with only public API knowledge, it answers questions about your codebase using information from its training data - open-source documentation, public GitHub

·No MCP servers are configured
·Agents rely solely on public API knowledge from training data

·Team is aware of MCP as a standard for agent-tool integration
·Integrations, if any, are manual (copy-paste between tools)

Evidence

·No MCP configuration files in repository or developer environment
·Absence of tool integration beyond IDE built-ins

What It Is

When an agent operates with only public API knowledge, it answers questions about your codebase using information from its training data - open-source documentation, public GitHub repositories, Stack Overflow, and official library references. It knows what the Stripe API looks like in general, what a typical PostgreSQL schema looks like, how Express.js middleware works. It does not know what your Stripe integration looks like, what your PostgreSQL schema looks like, or how your Express middleware is wired.

This state is almost universal at L1. The agent is genuinely helpful for generic programming tasks - "how do I write a regex that matches email addresses," "what does Array.reduce do," "show me an example of a React useEffect" - but degrades significantly the moment the question becomes internal. "What parameters does our UserService.create method accept?" gets answered with a guess based on what UserService.create usually looks like in public codebases. The guess is often structurally plausible but specifically wrong.

The core problem is that the agent has no way to distinguish between your API and the public API it was trained on. If your internal library wraps a popular framework and diverges from the default conventions, the agent will follow the public convention and produce code that fails at runtime. This failure mode is particularly insidious because the code looks correct - it would be correct for the standard library. Only a developer who knows the internal divergence will catch it.

Why It Matters

Hidden correctness degradation - agents confidently produce wrong internal-API usage without any signal that they're guessing; the errors surface later in testing or code review, not at generation time
Quantifies the context gap - measuring how often agents suggest the wrong internal API variant reveals exactly how much value is being lost to the public-API-only limitation
Makes internal library investment risky - teams that build internal abstractions on top of popular libraries are penalized at this level; the more your codebase diverges from public conventions, the worse agent output quality becomes
Motivates the simplest MCP investment - pointing an agent at your actual source code (via a filesystem MCP server or Claude Code's native file access) immediately closes the gap for the most common failure mode
Differentiates agent types - understanding this limitation helps teams route tasks correctly: use agents for generic tasks where public knowledge is sufficient, and route internal-API tasks to agents with actual codebase access

Getting Started

Catalog your internal divergences - identify where your codebase deliberately deviates from public conventions: custom wrappers, renamed methods, non-standard configuration, internal service APIs. These are the highest-risk areas for public-API-only agents.
Test agent accuracy on internal APIs - pick 10 real internal API usage examples and ask your agent to write them from scratch. Score how many are correct without correction. This number is your baseline accuracy on internal context.
Enable file access in your AI client - Claude Code and Cursor both support reading local files natively, without MCP servers. This is the fastest way to give an agent internal context. Ensure your developers know how to add relevant files to the agent's context window.
Create an internal API cheat sheet - for the highest-divergence internal APIs, write a short description of how they differ from the public convention. Keep it as a markdown file that developers can paste into agent context. This is a manual workaround until proper MCP integration is in place.
Add internal docs to a basic MCP server - the step beyond manual file-pasting is a docs MCP server that exposes your internal documentation. Even a simple server that reads from a local directory of markdown files dramatically improves agent accuracy on internal APIs.

Tip

Before investing in MCP servers, try adding a CLAUDE.md file at the root of your repository documenting your key internal conventions and divergences from public defaults. Claude Code reads this file automatically. It costs 30 minutes to write and immediately improves agent accuracy on internal patterns.

5 steps to get from here to the next level

Common Pitfalls

Assuming the model "knows" your internal library because it's based on a popular framework. If your internal HTTP client wraps Axios but changes the method signatures, the agent will use Axios signatures. Wrapping does not inherit documentation in the model's training data. Every internal abstraction is invisible to a public-knowledge-only agent.

Using agents for internal API integration tasks without checking output. Developers who trust agent output without verification on internal API usage will ship bugs. The output looks correct. A review process that treats agent-generated internal API calls as requiring human verification catches these errors before they reach production.

Not updating the agent when internal APIs change. Even when developers do provide internal API context (via pasted docs or file context), they often paste outdated versions. Internal APIs evolve; the context provided to agents often doesn't. A doc MCP server that reads from the live internal documentation directory solves this; manual paste workflows do not.

Conflating IDE autocomplete with API knowledge. IDE language servers and type-aware autocompletion tools do know your internal APIs - they parse your actual codebase. This is different from agent knowledge. A developer might see correct autocomplete suggestions from their IDE and assume the AI chat assistant has the same knowledge. It does not.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob's team is building on top of an internal platform layer that wraps several external services. Senior developers know the internal conventions well, but new hires and the AI agents they use keep using the external service APIs directly instead of the internal wrappers. This causes subtle bugs and requires senior developers to spend time in code review catching incorrect API usage.

What Bob should do: Bob should treat internal API accuracy as a first-class engineering concern. The immediate fix is documentation: every internal wrapper should have a short doc explaining what it wraps, what it changes, and what the correct usage looks like. These docs should be in the repository so that both human reviewers and AI agents can reference them. The medium-term fix is a basic MCP server that serves this internal documentation to agents automatically. Bob should assign this as a one-sprint infrastructure task rather than treating it as an ongoing drag on senior developer time.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah notices that junior developers and new hires using AI tools produce code with more internal API mistakes than senior developers using the same tools. The seniors catch the mistakes in review, but the back-and-forth is adding review cycles and slowing delivery. She suspects the AI tools are part of the problem.

What Sarah should do: Sarah should run a targeted experiment: give three new developers the same set of tasks, one group with current AI tools only, one group with a curated internal API reference added to their agent context. Compare the number of internal API corrections needed in code review. The group with internal API context will show fewer corrections. This experiment produces the evidence needed to justify a small infrastructure investment - a docs MCP server or even a well-maintained CLAUDE.md file - that closes the context gap for the whole team.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor has personally solved this problem for himself by maintaining a detailed CLAUDE.md file and a set of internal API snippets he pastes into agent context when working on integration tasks. His agent output quality is noticeably higher than his colleagues', but the solution doesn't scale - it depends on his personal knowledge of what context to provide.

What Victor should do: Victor should systematize his personal workaround into team infrastructure. First, he should publish his CLAUDE.md template as a team standard. Second, he should build a simple MCP server that serves the internal API documentation directory - not a complex server, just a filesystem server pointed at the right directory. Third, he should run a session with his team showing the before/after difference in agent output quality with and without internal context. Victor's personal effectiveness is evidence of what's possible; his job is to make that effectiveness accessible to everyone on the team, not just himself.

What Victor should do - role-specific action plan

From the Field

Recent releases, projects, and discussions relevant to this maturity level.

releaseL1

openai/codexrust-v0.117.0-alpha.19OpenAI issued rust-v0.117.0-alpha.19 of the Codex library, a pre-release iteration indicating ongoing development of Rust-native bindings for code-specialized mgithub.com

MCP & Tool Integration

Zero MCP Integrations: copy-paste