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 technique to lengthen APIs to agentic methods and generative AI coding instruments. For simple use instances, it may well work. However usually it doesn’t.

You need to design your instruments for a way giant language fashions (LLMs) and agentic methods work. With out this, you danger failed software calls, unsuitable parameter values, and retries that waste context and degrade efficiency. On this publish, we present the place MCP software design goes unsuitable and repair it with sensible context engineering approaches.

Two issues are behind most of those failures. The primary is bloat. Instrument 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 devour important context earlier than the consumer has requested a single query. As context fills, an LLM’s capability to cause can degrade and trigger the session to grow to be much less productive.

The second is confusion. As reasoning degrades, the LLM makes poorer decisions, calls the unsuitable software and chooses incorrect parameters. Subsequent retries compound the problem by additional contributing to bloat. Semantic similarity between instruments, too many choices, and ambiguous naming additionally contribute to confusion. A standard resolution is to complement 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 situation you might be working to resolve.

This sample is frequent. Your agent makes surprising decisions, the context fills before anticipated, and your session rapidly turns into much less helpful. Addressing bloat and confusion is a context engineering drawback. 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 fancy 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 Okay-12 content material search API utilizing the MCP protocol. You’ll run them domestically and work together with them utilizing Kiro CLI to check the variations your self.

Approaches and tradeoffs

The approaches we share deal with these points on the software stage. Some form what the LLM sees or when it sees it. Others change how instruments are structured. As you apply them, it is advisable perceive how they influence bloat and confusion to search out the appropriate steadiness between the 2.

Descriptions and responses

The pure first step to fixing MCP software habits is to enhance the descriptions. A dependable technique to cut 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 rapidly add to bloat. Context and value can develop rapidly when many MCP servers are loaded right into a consumer.

What the software returns shapes habits too. A software that returns 50 fields per consequence fills context rapidly. If 5 are adequate for a call, default the response to these fields and supply a separate choice to request an in depth view. Shifting to an on-demand strategy for detailed output cuts response tokens by roughly two-thirds, based on 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 alter. A response that returns solely “no outcomes” offers it nothing, inflicting the mannequin to both hand over or maintain 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 fully. Take into account the next to handle frequent schema points:

• Rename parameters to match how the LLM would possibly 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 inside conference.
• Set defaults to the most typical 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 not often used or that the LLM can not use nicely.

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 may 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 centered. Anthropic’s Instrument Search Instrument and Amazon Bedrock AgentCore Gateway present these ideas utilized at scale. Anthropic experiences as much as 85% token discount by loading software definitions solely when related.

Expertise are one other instance of lazy loading, however applied consumer facet. These native information comprise helpful context for the software however are solely learn into context when related. This reduces the trouble to implement and distribute them. However there isn’t any assure that the talent masses 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, you could not management which LLM calls your MCP instruments. An outline tuned towards one mannequin would possibly confuse one other. Totally testing all of the potential fashions a consumer would possibly use is unrealistic.

One technique to deal with that is so as to add an introspection software that instantly calls an exterior LLM. The consumer 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 possibly can correctly immediate engineer this software and check with golden queries. The consumer 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 targeted, a smaller, sooner mannequin handles this activity nicely and retains prices affordable at scale.

Agentic instruments

While you want accuracy and full management, the subsequent logical development is to again your complete MCP server with an agent of your personal. The introspection instance handles a single interpretation step, however an agentic software handles your entire interplay. The instruments grow to be pure language endpoints to the consumer. It states what it wants, and your agent does the remainder. The opposite strategies coated nonetheless apply. The tradeoffs are yours to personal fully, however as with introspection, you possibly can totally engineer the habits with the mannequin of your alternative.

The following part walks by means of working code that applies these approaches towards the identical backend and check queries, so you possibly can evaluate their habits instantly.

Walkthrough

Every of the 6 variations wraps the identical simulated Okay-12 content material search backend with a unique 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.

Conditions

You want the next to run the pattern code:

Clone the pattern code repository and observe the repository README for detailed stipulations, set up, and server startup directions. The walkthrough that follows assumes all six variations are working.

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

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

Take a look at queries

These queries return actual outcomes from the pattern database. Attempt them towards every model:

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

As you run by means of every model:

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

To change 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 inside 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 steering.

The software definition is small, however the LLM has no steering on what values are legitimate. Attempt the primary question. It would move “quiz” for media_type when the legitimate worth is “Evaluation”, or “math” when the sector expects “Math”. Every unsuitable alternative triggers a retry that consumes extra context. The one clue that one thing went unsuitable is an empty consequence. The LLM is left guessing what to alter on the subsequent try. Low baseline price is deceptive when confusion drives up the precise price by means of 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 steering on which filters so as to add, slightly 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 increased, however fewer retries usually make the whole decrease.

V3: Schema and defaults

v3_rethought_schema.py

This model renames parameters to match how the LLM thinks and constrains values by means of 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 sort that lists legitimate choices instantly within the schema. Wise defaults deal with the frequent case: construction="Asset", resource_class="Pupil Useful resource", language="en". A separate get_resource_detail software handles drill-down. This is applicable the restructuring strategy, giving every software a transparent job and retaining search responses concise.

Enums assist stop unsuitable values on the protocol stage. 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 a substitute of embedding enums and detailed descriptions within the search software, this strategy 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 an inventory 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 up to now. 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 fully and search instantly. Widespread values within the hints deal with frequent queries with out a round-trip, whereas the complete taxonomy is obtainable for edge instances. As a result of the taxonomy masses 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 complicated software schemas it compounds rapidly.

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 useful filter values with rationale explaining every alternative. It interprets “TEKS-aligned content material for youths engaged on dividing in center college” and returns really useful filters: topic “Math”, grades 6-8, state_standard “TX-TEKS”, subject “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. Swap fashions with /mannequin and evaluate V4 versus V5. With out introspection, weaker fashions produce inconsistent outcomes. With introspection, outcomes keep steady.

V6: Agent-as-tool

v6/app/v6/fundamental.py

The ultimate model exposes a single MCP software backed by a Strands Brokers agent with its personal system immediate and inside 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 consumer LLM doesn’t see.

Attempt all 5 queries and evaluate consumer context utilization to the opposite variations. The consumer LLM does minimal work. Conduct is constant no matter which consumer 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 change for direct management over habits and consistency. Swap between fashions with /mannequin in Kiro and see outcomes stay steady throughout fashions.

Tradeoffs at a look

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

After working the check queries throughout all 6 variations, discover the patterns. V2 is the quickest path to higher 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 best alternative will depend on your subject depend, vocabulary stability, latency price range, and the way a lot you want constant habits throughout completely different purchasers.

Cleansing up

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

Conclusion

MCP itself is just not the issue. It’s a key protocol for agentic options. The issue is software design. The approaches on this publish deal with bloat and confusion by means of context engineering on the software stage. The code walkthrough demonstrates every strategy towards the identical situation so you possibly can observe the tradeoffs instantly and resolve what matches your state of affairs.

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 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 by means of a single connection. Research the way it makes use of on-demand talent loading to maintain context lean.
• Strands Brokers SDK – Go deeper on the agentic strategy from V6. Construct multi-turn brokers with software orchestration, reminiscence, and testable habits.
• Amazon Bedrock AgentCore – Deploy your MCP server with out managing infrastructure. Consists of 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 towards the bloat and confusion framework from this publish.
• Amazon Bedrock AgentCore Samples – Getting-started guides, function 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.
• Steerage for Vibe Coding with AWS MCP Servers – A pattern lodge reserving utility demonstrating how AI coding assistants use AWS MCP servers to speed up growth with AgentCore.

In regards to the authors