Subagents and MCP

By the Syncfusion DevTutorials team · Last updated October 22, 2026

Why big tool output pushes your rules out of the agent's context, and why an agent without a way to look things up guesses. You add a log-searching subagent and an MCP server, in Claude Code, Codex and Cursor, so the rules stay in view and the agent calls the real API.

Subagents and MCP

Your harness works for one task at a time. Now the tasks get bigger and noisier.

Two new problems show up:

• Big tool output fills the agent's memory. Your rules fall out.
• The agent needs a fact it cannot see. So it guesses.

This lesson fixes both.

Subagent = a helper agent with its own, separate context window.

MCP server = a small program that gives the agent tools to look up real facts.

For example:

• A subagent reads six long log files. It sends back five short lines.
• An MCP server answers "what is the real export URL?" from the API itself.

A Real-World Example

Think about a manager with a small desk.

The manager reads six thick reports. Now the desk is buried.

The sticky note that says "do not touch the payroll file" is under the pile.

So the manager asks an assistant: "Read these reports. Tell me in five lines why the export fails."

The assistant works at a different desk.

The manager gets back one short note. The sticky note stays in view.

And when the manager needs a phone number, they look it up in the company directory. They do not guess.

In a harness:

1. The assistant is a subagent.
2. The company directory is an MCP server.

The Export feature is broken. The agent must find out why.

There are six log files. Your rules say: never edit the production settings file.

Click the button and open the Sessions & App tab.

• The context count: it grows with every log the agent reads.
• The last edit: the agent changes .env.production (or Pricing.Api/appsettings.Production.json).
• The rules: they said never to touch that file.

Simple lesson: big output pushes the rules out, and then the agent breaks them.

What You Will Learn

In this lesson, you will learn:

1. How tool output can push your rules out of the context window.
2. What a subagent is, and how to write one for Claude Code, Codex and Cursor.
3. How to make the main agent use the subagent.
4. What MCP is, and how to add an MCP server.
5. When work belongs in a subagent, an MCP server or the main agent.

Keep the Main Context Small

How Big Output Crowds the Window

In Context Windows, the limit hit across sessions. It hits inside one session too.

The context window (see Coding Agents) holds everything the agent reads:

• the rules
• the code
• every tool result

Big tool output, like a long log, fills the window fast.

Real tools usually compact a long chat and keep the rules file. But details get summarised away, and every log line costs tokens.

In this lab, the model is simpler: when the window is full, the oldest text drops out, and the rules go first. That makes the cost easy to see.

Step through all five frames.

• Frames 1 to 3: the bar fills up, one log at a time. In this lab, the rules go grey when it overflows.
• Frame 4: what the agent did. Six reads, then an edit to a protected file.
• Frame 5: the same job with a subagent. The main context stays almost empty.

What a Subagent Does

A subagent is a second agent that the main agent can call.

• It gets its own fresh context window.
• It reads what it needs in that window.
• It sends back only a short answer.

Its big reads never enter the main context.

The work is the same. Only the place where the tokens land is different.

The Description and the Rules Line

The main agent must know when to call the subagent. Two things tell it.

Description = one line in the subagent file. It says what the subagent does and when to use it.

Write it like a skill description. "Helper" is not enough.

"Searches the log files and returns only the lines that explain an error" is good.

The rules line makes it certain. Name the subagent there, with its exact name:

- For any search through logs/, use the log-searcher subagent. Do not read the logs yourself.

Simple lesson: a clear description plus a rules line with its name makes the agent use it.

Stop Guessing with MCP

The Agent Guesses

Now the logs are handled. But the fix needs the orders API.

The agent has no way to look up the URL.

Click the button and look at the last two steps.

• The URL: it calls /api/orders/export.
• The answer: 404. That URL does not exist.
• The real URL: /v2/orders/export.csv.

What MCP Is

MCP = Model Context Protocol. It is an open standard for connecting an agent to outside tools and data.

An MCP server offers those tools. Here, the orders server can say which export URL is real.

Without it, the agent only has its memory of how APIs usually look. Your API is not usual.

Step through all three frames.

• Frame 1: the guess, and the 404.
• Frame 2: the MCP file, with the orders server.
• Frame 3: the same job, side by side. The MCP run asks first and gets 200.

Simple lesson: look facts up. Do not let the agent guess them.

The Files in Each Tool

One Setup, Three Tools

The idea is the same in every tool. The paths and the format change.

Step through all three frames.

• Frame 1: the two files in Claude Code. The marked lines are the name, the description and the server name.
• Frame 2: where Cursor and Codex keep the same two files.
• Frame 3: the same lab check passes in all three tools.

The Codex subagent format is still new. Check the Codex docs before you copy it.

Lab Exercise: A Subagent for Logs, MCP for the API

Make three changes in the lab, in your tool's folders:

1. Add a subagent file named log-searcher. Its description must say that it searches logs.
2. Add a rules line that tells the agent to use it, by name, for any log search.
3. Add an MCP server named orders in your tool's MCP file.

Click the button, make the changes, then press Check my harness.

• The check: it runs all 3 versions.
• To pass: the rules stay in view, and the production settings file stays untouched.
• And: the export calls the real URL.

Simple lesson: one subagent, one rules line and one MCP server fix both problems.

Who Does Which Job

Main Agent, Subagent or MCP Server

Ask one question per job:

• Is the output big and noisy? Give it to a subagent.
• Is it a fact from outside the code? Get it from an MCP server.
• Is it short and direct, like one small edit? Keep it in the main agent.

Examples Across the Team

• Planning: a planner sends "read the old billing module" to a subagent. It writes feature_list.json from the short summaries.
• Frontend: a test-runner subagent runs pnpm test and returns only the failures. A design-system MCP server lists the real colour tokens.
• Backend: a subagent reads long dotnet test output and returns the failing test names. An MCP server for the OpenAPI file stops guessed routes.
• Integration: logs and other teams' APIs. That is exactly this lesson's case.

Simple lesson: every team has noisy output and outside facts.

TL;DR

1. Context window = everything the agent can see at once. Big output pushes the rules out.
2. Subagent = a helper with its own window. It reads the noise and sends back a short answer.
3. Description = the line that says what the subagent does and when to use it.
4. Rules line = names the subagent, so the main agent always uses it.
5. MCP = Model Context Protocol, a standard way to plug in tools.
6. MCP server = a program that looks up real facts, such as API URLs.
7. Paths = .claude/agents + .mcp.json, .cursor/agents + .cursor/mcp.json, .codex/agents + .codex/config.toml.

Common mistakes

Check Your Understanding

Exercises

These exercises practise subagents and MCP from this lesson.

Press Check when you are ready. Use Show Hint if you get stuck.

What to Remember

• Everything the agent reads goes into its context window. Big output pushes the rules out.
• A subagent works in its own window and returns a short summary. Name it in the rules file.
• The description says what the subagent does and when to use it. Give it only the tools it needs.
• An MCP server lets the agent look up facts, such as real API URLs, instead of guessing.
• Each tool reads its own folder: .claude, .cursor or .codex.
• Noisy reading goes to a subagent, facts come from MCP, and small edits stay with the main agent.

Further Reading

• Skill issue: harness engineering for coding agents, by HumanLayer: subagents and MCP as parts of the harness, and how to keep context small.
• Harness design for long-running application development, by Anthropic: separate agents with their own context for planning, building and judging.
• awesome-harness-engineering, by walkinglabs: subagents, MCP and context management across tools.

Next: Architecture Tests. A test that guards your layers keeps the code tidy as agents add more of it.