MCP software design: Sensible approaches and tradeoffs

When Mannequin Context Protocol (MCP) instruments underperform, the trigger is never the protocol itself however the software design. Many groups begin by exposing an current API as-is and trusting the agent to determine the remainder. It’s a pure option to prolong APIs to agentic programs and generative AI coding instruments. For simple use instances, it could possibly work. However typically it doesn’t.

You should design your instruments for the way giant language fashions (LLMs) and agentic programs work. With out this, you danger failed software calls, flawed parameter values, and retries that waste context and degrade efficiency. On this put up, we present the place MCP software design goes flawed and how you can repair it with sensible context engineering approaches.

Two issues are behind most of those failures. The primary is bloat. Software definitions load into the LLM’s context on each name, whether or not the software is used or not. A number of related MCP servers can eat vital context earlier than the consumer has requested a single query. As context fills, an LLM’s capacity to purpose can degrade and trigger the session to turn out to be much less productive.

The second is confusion. As reasoning degrades, the LLM makes poorer decisions, calls the flawed software and chooses incorrect parameters. Subsequent retries compound the difficulty by additional contributing to bloat. Semantic similarity between instruments, too many choices, and ambiguous naming additionally contribute to confusion. A typical answer is to counterpoint the software descriptions with clearer definitions, pure language mappings, and utilization examples. This does assist with confusion. However all the things added dangers worsening bloat and compounding the very subject you’re working to resolve.

This sample is widespread. Your agent makes sudden decisions, the context fills earlier than anticipated, and your session shortly turns into much less helpful. Addressing bloat and confusion is a context engineering downside. Context engineering shapes what the LLM sees and when it sees it, so the mannequin produces higher outcomes. Bettering one, or each, of those is a posh balancing act.

The next sections discover approaches and tradeoffs to handle these points. To make them concrete, we constructed a number of examples that expose a simulated Ok-12 content material search API utilizing the MCP protocol. You’ll run them regionally and work together with them utilizing Kiro CLI to match the variations your self.

Approaches and tradeoffs

The approaches we share tackle these points on the software degree. Some form what the LLM sees or when it sees it. Others change how instruments are structured. As you apply them, you have to perceive how they affect bloat and confusion to search out the appropriate stability between the 2.

Descriptions and responses

The pure first step to fixing MCP software conduct is to enhance the descriptions. A dependable option to scale back confusion is to make clear what values imply, how pure language maps to them, and what the software is for. However take it too far, and also you shortly add to bloat. Context and value can develop shortly when many MCP servers are loaded right into a shopper.

What the software returns shapes conduct too. A software that returns 50 fields per consequence fills context shortly. If 5 are adequate for a choice, default the response to these fields and supply a separate choice to request an in depth view. Shifting to an on-demand method for detailed output cuts response tokens by roughly two-thirds, in keeping with Anthropic’s analysis.

Correct error messages are one other method to enhance effectivity. When a software name fails, useful errors can steer the subsequent try. A response that claims “search requires 2 or extra phrases in question” tells the LLM precisely what to vary. A response that returns solely “no outcomes” offers it nothing, inflicting the mannequin to both hand over or preserve guessing.

Schema constraints

The place descriptions and correct errors information the LLM towards appropriate values, schema constraints like enums and default values can take away the guesswork completely. Think about the next to handle widespread schema points:

• Rename parameters to match how the LLM may perceive the area, not how your database labels its columns.
  • A parameter known as resource_class with values like ‘Pupil Useful resource’ or ‘Trainer Assist’ is clearer for the LLM. A content_bucket column requires the LLM to know an inner conference.
• Set defaults to the commonest values so the LLM solely must specify what varies.
• Constrain finite-value fields with enums so the schema itself tells the LLM what’s legitimate.
• Drop fields which might be hardly ever used or that the LLM can’t use effectively.

Restructuring instruments and on-demand context

Splitting a multi-purpose software into a number of particular instruments gives readability to the mannequin and offers extra granular outcomes. A lazy loading discovery software is one instance. You’ll be able to take away complicated software descriptions from the always-loaded context and supply a separate software for on-demand retrieval. The LLM solely retrieves this context when the duty requires it. This retains context lean and targeted. Anthropic’s Software Search Software and Amazon Bedrock AgentCore Gateway present these ideas utilized at scale. Anthropic stories as much as 85% token discount by loading software definitions solely when related.

Abilities are one other instance of lazy loading, however carried out shopper facet. These native recordsdata comprise helpful context for the software however are solely learn into context when related. This reduces the hassle to implement and distribute them. However there isn’t a assure that the ability hundreds when wanted or stays unchanged as soon as put in.

Server-side inference

Context engineering is difficult when you don’t management which mannequin will interpret your directions. And as soon as deployed, it’s possible you’ll not management which LLM calls your MCP instruments. An outline tuned in opposition to one mannequin may confuse one other. Totally testing all of the potential fashions a shopper may use is unrealistic.

One option to tackle that is so as to add an introspection software that instantly calls an exterior LLM. The shopper makes use of pure language to question your introspection software and will get focused directions for utilizing the opposite instruments. Since you select the mannequin, you may correctly immediate engineer this software and check with golden queries. The shopper LLM nonetheless makes the ultimate software name, however your LLM interprets the necessity and gives appropriate values. As a result of the use case is concentrated, a smaller, sooner mannequin handles this job effectively and retains prices cheap at scale.

Agentic instruments

If you want accuracy and full management, the subsequent logical development is to again your total MCP server with an agent of your individual. The introspection instance handles a single interpretation step, however an agentic software handles the complete interplay. The instruments turn out to be pure language endpoints to the shopper. It states what it wants, and your agent does the remainder. The opposite methods lined nonetheless apply. The tradeoffs are yours to personal fully, however as with introspection, you may totally engineer the conduct with the mannequin of your alternative.

The subsequent part walks via working code that applies these approaches in opposition to the identical backend and check queries, so you may evaluate their conduct instantly.

Walkthrough

Every of the 6 variations wraps the identical simulated Ok-12 content material search backend with a special MCP software design. The backend has 14 filterable fields (topic, grade, format, requirements alignment, language, useful resource class, and others) with managed vocabularies. The problem for the LLM is bridging the hole between how a instructor phrases a request and the precise values these fields settle for. V1 begins with the uncooked passthrough that leaves this hole open. Every later model closes it otherwise.

Stipulations

You want the next to run the pattern code:

Clone the pattern code repository and comply with the repository README for detailed conditions, set up, and server startup directions. The walkthrough that follows assumes all six variations are operating.

No infrastructure is deployed to AWS. You run all code regionally. Inference calls to Amazon Bedrock are the one price apart out of your coding shopper. See Amazon Bedrock pricing for present charges.

This walkthrough assumes you’re utilizing Kiro and have run python scripts/setup_agents.py from the repository.

Check queries

These queries return actual outcomes from the pattern database. Attempt them in opposition to every model:

1. “Discover me a quiz on fractions for my seventh graders.”
2. “Do you’ve gotten any classes for educating Spanish in center faculty?”
3. “I would like TEKS-aligned content material for youths engaged on dividing in center faculty.”
4. “What kinds of content material can I seek for?”
5. “Can I get particulars on n-sc-1096?”

As you run via every model:

• Observe whether or not the LLM picked the appropriate filter values on the primary name.
• Notice what number of software calls it took.
• Examine whether or not the response included info the LLM didn’t want.
• Observe how shortly the context window fills. Examine the proportion displayed in Kiro, or use /context present for an in depth breakdown.

To modify between variations, use /agent swap (for instance, /agent swap v1-passthrough). Clear context with /clear between variations so prior outcomes don’t affect the subsequent one.

V1: Uncooked passthrough

v1_passthrough.py

The primary model is the baseline anti-pattern. It exposes the backend API instantly. The software definition has 14 parameters with inner names like self-discipline, media_type, content_bucket, and a one-line docstring that claims “Performs a worldwide seek for academic sources.” No legitimate values listed, no pure language mappings, no steerage.

The software definition is small, however the LLM has no steerage on what values are legitimate. Attempt the primary question. It’d move “quiz” for media_type when the legitimate worth is “Evaluation”, or “math” when the sector expects “Math”. Every flawed alternative triggers a retry that consumes extra context. The one clue that one thing went flawed is an empty consequence. The LLM is left guessing what to vary on the subsequent try. Low baseline price is deceptive when confusion drives up the precise price via churn.

V2: Wealthy descriptions

v2_better_descriptions.py

Similar construction as V1, zero backend refactoring. The docstring now lists legitimate values and synonym mappings for every subject. For instance, self-discipline exhibits “Legitimate: Math, Science, Literacy/ELA…” and media_type maps “‘quiz’/‘check’ → Evaluation, ‘worksheet’ → Exercise.” It additionally distinguishes fuzzy search (key phrase) from strict filters (all the things else). Three rarely-used parameters are dropped and error messages now return steerage on which filters so as to add, relatively than an empty consequence.

Attempt the identical queries. Accuracy improves instantly as a result of the LLM sees legitimate values and synonym mappings. The software definition is noticeably bigger. That’s the bloat tradeoff. Each name pays it whether or not the software is used or not. After 5 queries, evaluate complete context consumed to V1. The per-call overhead is greater, however fewer retries typically make the full decrease.

V3: Schema and defaults

v3_rethought_schema.py

This model renames parameters to match how the LLM thinks and constrains values via the schema itself. Parameters are renamed: self-discipline turns into topic, content_bucket turns into resource_class. Every finite-value subject makes use of a Literal kind that lists legitimate choices instantly within the schema. Wise defaults deal with the widespread case: construction="Asset", resource_class="Pupil Useful resource", language="en". A separate get_resource_detail software handles drill-down. This is applicable the restructuring method, giving every software a transparent job and maintaining search responses concise.

Enums assist forestall flawed values on the protocol degree. Defaults imply the LLM solely specifies what varies. The response features a defaults_applied subject so the LLM is aware of what was filtered implicitly. The definition is smaller than V2 as a result of names and enums do the work that verbose descriptions did earlier than. Run the queries and evaluate accuracy to V2. Accuracy improves whereas context drops.

V4: Lazy loading (restructuring)

v4_lazy_loading.py

As an alternative of embedding enums and detailed descriptions within the search software, this method strikes them behind a separate software. The search software retains solely brief trace descriptions like “Topic space, e.g. ‘Math’, ‘Science’, ‘Literacy’”. A get_taxonomy software takes a listing of subject names and returns legitimate values and pure language mappings just for the fields related to the present question.

The search software definition is the leanest thus far. Discover the software calls. For ambiguous queries, the LLM calls get_taxonomy earlier than looking out to verify legitimate values. For simple queries the place the hints are adequate, it would skip the taxonomy name completely and search instantly. Widespread values within the hints deal with frequent queries with out a round-trip, whereas the total taxonomy is offered for edge instances. As a result of the taxonomy hundreds solely when wanted, each prior interplay within the session runs with out that context price. The financial savings on this instance is modest, however in environments with many related instruments and sophisticated software schemas it compounds shortly.

V5: LLM introspection

v5_llm_introspect.py

This model provides an introspect software backed by Amazon Nova 2 Lite on Amazon Bedrock. The introspect_query software takes the instructor’s natural-language query and returns really helpful filter values with rationale explaining every alternative. It interprets “TEKS-aligned content material for youths engaged on dividing in center faculty” and returns really helpful filters: topic “Math”, grades 6-8, state_standard “TX-TEKS”, matter “dividing,division”.

Kiro nonetheless makes the ultimate search name. As a result of introspect runs on a mannequin of your alternative, immediate engineering and testing are dependable. The interpretation occurs server-side, so your context stays lean. The tradeoff is price. You pay for the server name however outcomes keep constant no matter which mannequin Kiro makes use of. Change fashions with /mannequin and evaluate V4 versus V5. With out introspection, weaker fashions produce inconsistent outcomes. With introspection, outcomes keep secure.

V6: Agent-as-tool

v6/app/v6/essential.py

The ultimate model exposes a single MCP software backed by a Strands Brokers agent with its personal system immediate and inner instruments. The exterior interface is one software with one parameter: agentic_search_content(query: str). Your agent handles taxonomy lookup, search, element retrieval, and response formatting internally utilizing its personal instruments that the shopper LLM doesn’t see.

Attempt all 5 queries and evaluate shopper context utilization to the opposite variations. The shopper LLM does minimal work. Habits is constant no matter which shopper connects as a result of your agent owns the reasoning. Dialog historical past persists throughout calls, so follow-up questions work naturally. The tradeoff is price and latency in alternate for direct management over conduct and consistency. Change between fashions with /mannequin in Kiro and see outcomes stay secure throughout fashions.

Tradeoffs at a look

Every model trades one price for an additional. This desk lays them facet by facet.

After operating the check queries throughout all 6 variations, discover the patterns. V2 is the quickest path to raised outcomes with no refactoring. V4 has the leanest baseline context. V5 handles ambiguous queries that different variations miss. V6 offers you essentially the most management on the highest infrastructure price. No model wins throughout all dimensions. The precise alternative is determined by your subject depend, vocabulary stability, latency finances, and the way a lot you want constant conduct throughout totally different purchasers.

Cleansing up

All servers run regionally. To cease them, run scripts/stop_all.sh from the repository root. See the accompanying repository README for particulars.

Conclusion

MCP itself just isn’t the issue. It’s a key protocol for agentic options. The issue is software design. The approaches on this put up tackle bloat and confusion via context engineering on the software degree. The code walkthrough demonstrates every method in opposition to the identical situation so you may observe the tradeoffs instantly and resolve what suits your scenario.

The protocol continues to evolve. The MCP 2026 Roadmap addresses transport scaling, agent communication, and options for enterprise deployment.

To go deeper, discover the next sources:

• MCP Methods on AWS – Covers the broader structure: which MCP patterns to make use of, when to attach a number of servers, and how you can construction your MCP system past a single software.
• AWS MCP Server – A managed MCP server that offers AI coding brokers entry to AWS APIs, documentation search, and curated agent abilities via a single connection. Research the way it makes use of on-demand ability loading to maintain context lean.
• Strands Brokers SDK – Go deeper on the agentic method from V6. Construct multi-turn brokers with software orchestration, reminiscence, and testable conduct.
• Amazon Bedrock AgentCore – Deploy your MCP server with out managing infrastructure. Contains runtime internet hosting, gateway for multi-server software discovery, and protracted reminiscence throughout classes.

For extra MCP code examples and patterns:

• Open Supply MCP Servers for AWS – 56 open supply MCP servers overlaying documentation, infrastructure, AI/ML, information, developer instruments, and extra. Decide one and consider its software descriptions in opposition to the bloat and confusion framework from this put up.
• Amazon Bedrock AgentCore Samples – Getting-started guides, characteristic demos, use-case examples, blueprints, and workshops for AgentCore.
• Pattern Serverless MCP Servers – Reference implementations for internet hosting MCP servers on AWS Lambda and Amazon Elastic Container Service (Amazon ECS), together with stateless and stateful patterns, plus Strands brokers on Lambda.
• Steering for Vibe Coding with AWS MCP Servers – A pattern resort reserving software demonstrating how AI coding assistants use AWS MCP servers to speed up improvement with AgentCore.

Concerning the authors