MCP makes tool integration feel easy.
That is the good news.
MCP also makes it easy to expose too much.
That is the part that sneaks up on teams.
One server becomes five tools.
Five tools become thirty tools.
Every tool gets a long description.
Every schema gets more fields.
Every prompt tries to explain the entire company.
Every resource wants to be available all the time.
Then the coding agent gets slower, noisier, and less decisive.
That is MCP context bloat.
The problem is not MCP itself.
The problem is weak information architecture.
The fix is to design servers around context boundaries.
This guide is for developers building MCP servers for coding agents.
It is practical.
It is opinionated.
It is not a replacement for the official specification.
Use it as a design review before your server becomes a prompt landfill.
Tiny landfill.
Very searchable.
Still not the dream.
The Practical Answer
Treat MCP as three different surfaces.
Tools are actions.
Resources are addressable context.
Prompts are reusable user-selected workflows.
Do not put everything into tools.
Do not put every document into the default context.
Do not use prompts as hidden system instructions.
Do not make one giant server that tries to describe the whole business.
A good MCP server gives the agent just enough capability to act.
It gives the host just enough resource structure to fetch context.
It gives the user clear prompts when a workflow should be chosen deliberately.
That division is the whole game.
Why Context Bloat Happens
Context bloat usually starts with good intentions.
The team wants the agent to know more.
The team adds another tool.
The team adds another description.
The team exposes another database table.
The team adds another prompt.
Then someone says, “The model can choose.”
Sometimes it can.
Sometimes it drowns in options.
Coding agents are especially sensitive to this.
They need repository context.
They need task context.
They need tool context.
They need runtime constraints.
If the MCP layer is noisy, it competes with the actual code.
That makes the agent worse at the thing you wanted it to do.
The Official Mental Model
The Model Context Protocol describes tools, resources, and prompts as separate server features.
Tools let servers expose actions that language models can invoke.
Resources let servers expose data that provides context to language models.
Prompts let servers expose reusable prompt templates and workflows.
That separation is not decorative.
It is a design hint.
A tool is not a document.
A resource is not always an action.
A prompt is not a secret policy layer.
When teams blur those boundaries, the server becomes confusing.
When the server is confusing, the agent spends more reasoning on server shape and less on user work.
Tools Should Be Few and Actionable
The MCP tools spec says tools are model-controlled.
That means the model can discover and invoke them based on context.
This is powerful.
It is also why tools should be designed carefully.
Every tool name and description becomes part of the model’s action menu.
If the menu is bloated, the model hesitates or picks the wrong thing.
Good tools are verbs.
Search issues.
Create branch.
Run query.
Fetch build log.
Open deployment status.
Bad tools are vague nouns.
Data manager.
Operations helper.
Everything API.
General admin.
If the tool name could mean ten actions, it is not a good tool name.
Tool Schema Design
A good schema is tight.
Use explicit fields.
Use enums where possible.
Use clear required fields.
Avoid accepting arbitrary strings when the domain has structure.
Avoid nested objects that mirror your entire internal API.
Avoid optional fields that change behavior in surprising ways.
The tool should guide the model toward a valid call.
The model should not need to reverse-engineer your backend.
If a tool needs a paragraph of warnings to be used correctly, consider splitting it.
If two modes have different side effects, split them.
If one parameter changes read-only behavior into destructive behavior, split it.
This is where safety and context efficiency become the same thing.
Resources Should Be Pull Context
Resources are different.
The MCP resources spec describes resources as URI-identified data that can provide context.
It also describes resources as application-driven.
That matters.
A resource does not need to be shoved into the model all the time.
It can be listed.
It can be selected.
It can be fetched when relevant.
That makes resources ideal for large or semi-static context.
Database schema.
Runbook.
API reference.
Project settings.
Deployment inventory.
Error catalog.
The point is addressability.
If the agent needs it, fetch it.
If it does not need it, leave it out.
Prompts Should Be User-Selected Workflows
Prompts are another separate surface.
The MCP prompts spec says prompts are designed to be user-controlled.
That means they are exposed with the intention that the user can explicitly select them.
This is perfect for reusable workflows.
Review this PR.
Write a migration plan.
Create an incident summary.
Generate a release note.
Prepare a test plan.
Do not use prompts as a place to hide global instructions.
Do not use prompts to smuggle huge policy documents into every session.
Do not create twenty prompts that differ only by one adjective.
Prompts should be discoverable and useful.
They should not be a junk drawer with markdown.
A Simple Classification Rule
Ask three questions.
Does it perform an external action?
Make it a tool.
Does it provide data or context that may be read?
Make it a resource.
Does it package a reusable workflow for the user to choose?
Make it a prompt.
If the answer is all three, split the design.
That is usually better than one overloaded surface.
The split may feel slower during implementation.
It pays back during usage.
Agents like clean affordances.
Humans do too.
The Anti-Pattern: One Tool Per Endpoint
Many teams map every internal API endpoint into a tool.
That is tempting.
It is also usually wrong.
Your internal API was designed for software.
The MCP tool list is also a model-facing action menu.
Those are not the same audience.
An endpoint can be low-level.
A tool should be task-level.
Instead of ten issue endpoints, expose two or three meaningful operations.
Search issues.
Get issue details.
Create issue comment.
Keep destructive actions separate.
Close issue should not hide inside update issue.
Delete issue should require a distinct, scary-looking action surface.
Yes, scary-looking.
Sometimes naming is a seatbelt.
The Anti-Pattern: Giant Tool Descriptions
Long descriptions feel helpful.
They are often a tax.
If every tool description becomes a mini manual, the agent carries too much context before the task begins.
Use short descriptions.
Put detailed documentation in resources.
Put examples in resources.
Use schema descriptions for field-level guidance.
Keep the tool description focused on what the tool does and when to use it.
If the tool has many constraints, maybe the tool is too broad.
If the constraints are domain documentation, make them a resource.
The Anti-Pattern: Always-On Resources
Resources can also bloat context.
The issue is not that resources exist.
The issue is when hosts or servers treat all resources as always relevant.
A database schema is useful when writing queries.
It is not useful when editing CSS.
A deployment runbook is useful during release triage.
It is not useful when renaming a test.
Context should be pulled by need.
This is where URI structure helps.
Use resource URIs that are easy to browse.
Use clear names.
Use short descriptions.
Use templates when the data is parameterized.
Do not make the agent read a library when it needs one page.
The Anti-Pattern: One Server for the Whole Company
The giant server is another common failure.
It exposes GitHub.
It exposes Jira.
It exposes Slack.
It exposes data warehouse queries.
It exposes deployment controls.
It exposes billing.
It exposes internal docs.
Then every coding session starts with a giant capability surface.
That is too much.
Split by domain.
Split by risk.
Split by audience.
Split read tools from write tools when needed.
Split local development tools from production operations tools.
The goal is not microserver theater.
The goal is meaningful boundaries.
A Better Server Design Pattern
Start with the workflow.
What does the coding agent need to do?
Fix a bug.
Investigate a failing test.
Read an issue.
Generate a release note.
Check a deployment.
Then define the smallest useful tool set.
For a bug workflow, maybe the server needs issue search and issue details.
For a release workflow, maybe it needs changelog resources and release-note prompts.
For deployment triage, maybe it needs read-only deployment status first.
Write actions can live behind a separate approval path.
This design follows the work.
It does not mirror the org chart.
Naming Rules
Tool names should be boring.
Boring is good.
Use verbs.
Use domain prefixes when aggregating servers.
Use stable names.
Avoid spaces.
Avoid cute names.
Avoid ambiguous abbreviations.
Good examples:
issues.search
issues.get
builds.get_log
deployments.status
docs.search
Weak examples:
helper
run
manage
query_everything
do_admin_stuff
The model cannot infer your office folklore.
Name the action.
Output Design Matters Too
Tool results can create context bloat after invocation.
Do not return twenty pages when the model needs a summary.
Return structured content when useful.
Return concise text when enough.
Return resource links for deeper context.
The tools spec allows tools to return resource links and embedded resources.
That is a useful pattern.
The tool can answer the immediate question.
Then it can point to a resource for more detail.
This keeps the first result small.
It also gives the agent a path to dig deeper.
That is much better than dumping everything upfront.
Security and Bloat Are Related
Security is not separate from context design.
The MCP tools spec says servers must validate inputs, implement access controls, rate limit invocations, and sanitize outputs.
It also says clients should prompt for confirmation on sensitive operations and show tool inputs before calling the server.
Those recommendations are easier to follow when tools are small.
A broad tool is harder to review.
A vague tool is harder to approve.
A giant output is harder to inspect.
A clean tool is safer because the human can understand it.
That is the practical security point.
Clarity reduces both model error and human error.
Before and After Example
Bad design:
{
"name": "company_admin",
"description": "Search, update, delete, export, sync, deploy, and manage company systems.",
"inputSchema": {
"type": "object",
"properties": {
"action": { "type": "string" },
"payload": { "type": "object" }
}
}
}
This is flexible.
It is also vague.
It hides risk inside action.
It gives the model too much room.
Better design:
[
{
"name": "issues.search",
"description": "Search readable engineering issues by keyword or status."
},
{
"name": "issues.get",
"description": "Fetch one issue by id."
},
{
"name": "issues.comment.create",
"description": "Create a comment on an issue."
}
]
This is less magical.
It is much easier to reason about.
The side-effecting action is visible.
The read actions are separate.
That is the point.
Design Review Checklist
Count the tools.
Read every tool name out loud.
Ask whether each tool is a task-level action.
Ask whether any tool combines read and write behavior.
Ask whether any tool accepts arbitrary action strings.
Ask whether the schema can be made tighter.
Ask whether large examples belong in resources.
Ask whether documentation belongs in resources.
Ask whether prompts are user-selected workflows.
Ask whether resources have clear URIs.
Ask whether outputs are concise by default.
Ask whether sensitive operations require confirmation.
Ask whether the server should be split.
Ask whether the coding agent needs this capability in every session.
That last question is brutal.
It is also the best one.
A Practical Default Architecture
For coding agents, I like three layers.
Layer one is local repo context.
That comes from files, tests, and commands.
Layer two is small MCP tools.
These are task-level actions that the agent can use when needed.
Layer three is pullable resources and user-selected prompts.
These provide deeper context without flooding the base prompt.
This architecture keeps the agent focused.
It gives capability without turning every session into a conference binder.
The binder had tabs.
Nobody read it.
You know the binder.
FAQ
What is MCP context bloat?
MCP context bloat is the unnecessary expansion of the agent’s available tool, resource, prompt, schema, and description surface until the model has more integration context than task-relevant context.
Should every API endpoint become an MCP tool?
No.
Expose task-level actions, not raw backend shape.
Internal APIs are for software integration.
MCP tools are also model-facing affordances.
When should I use a resource instead of a tool?
Use a resource when the server is exposing data or context that can be addressed, browsed, selected, or fetched.
Use a tool when the model needs to perform an action.
When should I use a prompt?
Use a prompt for reusable workflows that a user can explicitly select, such as code review, migration planning, release note drafting, or incident summaries.
Is context bloat a security issue?
It can become one.
Large vague tools and huge outputs are harder for both models and humans to inspect, approve, and audit.
๊ด๋ จ ๊ธ
- Codex Sandbox and Approvals: A Practical Security Checklist for Local AI Coding Agents
- Claude Code Subagents vs Hooks: When to Delegate, When to Automate, and When to Stay in the Main Thread
- Codex๋ฅผ ๋ต๋ณ๊ธฐ๊ฐ ์๋๋ผ ์์ด์ ํธ๋ก ์ฐ๋ ๋ฒ
Sources
- Model Context Protocol: Introduction
- Model Context Protocol: Tools specification
- Model Context Protocol: Resources specification
- Model Context Protocol: Prompts specification
Final thought.
MCP is most useful when the server design respects attention.
Give the agent clear actions.
Give the host addressable context.
Give the user explicit workflows.
Keep the base prompt clean.