--- title: "Build context-aware MCPs, not API wrappers" description: "MCP servers shouldn't just expose endpoints, they should adapt to their environment, using project context to guide AI reasoning and execution." date: "2025-10-04T20:37:36.000Z" url: "https://timbenniks.dev/writing/build-context-aware-mcp-not-api-wrappers" canonical_url: "https://timbenniks.dev/writing/build-context-aware-mcp-not-api-wrappers" image: "https://res.cloudinary.com/dwfcofnrd/image/upload/q_auto,f_auto/website/mcp-3.png" tags: ["composable-architecture", "ai-engineering", "api-design", "performance", "developer-experience"] reading_time: "5 min read" --- # Build context-aware MCPs, not API wrappers We keep teaching agents _how_ to use tools, but not _when_ or _why_. That's why most Model Context Protocol (MCP) servers fail: they offer power without perspective. You can see it happen. The model calls `getEntries`, then `getEntries` again, then hallucinates `publishBlogPost` because it has no idea what your content model looks like. It's like giving a mechanic a warehouse full of parts and no car to fix. **Context is the missing ingredient.** A well-designed MCP doesn't just expose capabilities, it understands _what_ the project is, _who_ the user is, and _why_ the operation matters. That awareness turns a general-purpose agent into a precision tool. ### Summary After building and testing multiple MCP servers, one thing stands out: **wrapping APIs isn't enough.** An effective MCP behaves like an _application_ that adapts to its environment. Without context, even the smartest agent becomes a confused one. - Avoid generic API wrappers. - Make MCPs **context-aware** so they adapt to each project or SaaS instance. - Dynamically adjust tool metadata, examples, and schemas at runtime. - Keep tool counts small (under 15) for accuracy and cost efficiency. - Treat context as the product, not a side feature. ### The illusion of control It's tempting to think that giving a model _more_ tools gives it _more_ control. The irony is the opposite: **real control comes from constraint and relevance.** Every tool you add expands the cognitive surface area. The model now has to _reason_ about which of the 30 functions to use before it even starts working. Context narrows that space, focuses attention, lowers cost, and increases confidence. ### The real definition of MCP For those new to it: MCP defines how large language models connect to external tools and systems. You can think of it as the “API layer” for AI reasoning, a contract that says, _here's what you can do, and here's how to do it safely._ Each tool in MCP has: - A **name** and **description** (to inform the model), - A **schema** for inputs and outputs, - A few **examples** to ground usage. Most implementations stop there. They register endpoints and call it a day, like deploying a CMS with no templates or editorial rules. It's technically functional but contextually blind. ### The problem of excess tools Once you load up a server with more than ~15 tools, smaller or cheaper models start to fall apart. They hallucinate tool names, confuse parameters, or loop on irrelevant reasoning steps. Why? Because the model's attention budget is finite. Every tool definition consumes context-window space, and every extra option increases cognitive load. In other words, the model stops thinking and starts guessing. The fix isn't smarter reasoning loops, it's **shrinking and specializing**. Expose fewer tools, and make each one deeply contextual. The model should only see the affordances that matter **right now**. ### Generic vs. context-aware MCPs Feature | Generic MCP | Context-aware MCP :--|:--|:-- Tool count | 30+ | <15 Descriptions | Static | Project-specific Examples | Generic API calls | Based on real data Schema | Universal | Tailored per project Model accuracy | Unstable | Precise and low-cost ### Building context-aware MCPs Here's where MCP gets interesting, and where most implementations fail. A context-aware MCP behaves like an app that **assembles itself dynamically**: - It fetches project metadata, schemas, or permissions at startup. - It rewrites tool descriptions to match the project's language and domain. - It generates examples that reflect _real_ workflows. - It adjusts tool visibility depending on user role, active features, or current task. In short, your MCP becomes a _contextual orchestrator_ rather than a static gateway. Think of it as the backend equivalent of “visual editing” for agents, the model sees a filtered, project-specific version of reality, not the entire universe of possibilities. ### A practical example Imagine integrating with a headless CMS. An average MCP wrapper might expose: - `getEntries` - `createEntry` - `publishEntry` - `getAssets` A context-aware version could: - Detect the active content model and generate field-specific schemas. - Rename tools to match editorial language (e.g., “update blog post” instead of “update entry”). - Limit access to only relevant content types. - Inject examples based on actual API usage (e.g., “publish the latest blog post in French”). This contextualization doesn't just improve accuracy, it **reduces cost** by cutting reasoning noise. ### The trade-offs of dynamic MCPs Dynamic MCPs are harder to build and test. They blur the line between infrastructure and application logic. You'll need caching, authentication, and version control for your dynamically generated toolsets. But the complexity pays off: faster responses, fewer hallucinations, cleaner execution logs, and long-term scalability. Most importantly, it future-proofs your MCP for multi-model, multi-tenant environments. ### The evolution toward adaptive middleware As agent ecosystems mature, MCP servers will evolve from “tool catalogs” into **context providers**. OpenAI's work on _context connectors_ and _semantic grounding_ points in that direction, the line between “server” and “app” will keep fading. Expect to see: - **Auto-contextual MCPs** that build tool definitions from embeddings or metadata. - **Role-aware schemas** that adapt access by persona. - **Composable MCP layers** that federate across GitHub, Notion, and Vercel automatically. In that world, MCP servers become the new middleware: intelligent, adaptive, and domain-aware. ### The conclusion An MCP server isn't just a set of endpoints. It's a **contextual engine** that mediates between models and systems. When it adapts to the project, the user, and the model's limits, it transcends the “API wrapper” stage and becomes something more powerful, _an application with awareness._ Tomorrow's agents won't just integrate with systems, they'll **inhabit** them. And context, not capability, will define intelligence. _That's how we make agents faster, cheaper, and genuinely useful._