Build your own multi-agent system: a developer's starting guide
To build a multi-agent system, start with one loop: an agent that calls tools, one of which runs another agent. You can expose a CLI agent through MCP, as Claude Code does with claude mcp serve, or call it as a subprocess. Add shared state and logs before adding more agents.
Start small
A multi-agent system is not a special kind of program. It is one agent loop that can call a tool, where the tool happens to be another agent. Build that first. Add a second agent only when one agent clearly cannot do the job, such as when you need separate contexts, different permissions or parallel work.
Pattern: agent as a tool
Wrap the second agent so the first sees it as a function with a clear input and output. You can do this three ways: a subprocess call to a command line agent, an HTTP API you write around it, or an MCP server. The subprocess is quickest and good for scripts. MCP is best when you want different clients to reuse the same tool.
Call another agent from Claude Code
Claude Code can run as an MCP server over stdio. Another client can then use it as a tool. The command, from the Claude Code documentation:
claude mcp serveConnect to a remote MCP server
To add a remote server to Claude Code, use the HTTP transport. Replace the name and URL with your own.
claude mcp add --transport http <name> <url>Claude Code subagents
If you only need helpers inside Claude Code, define subagents as Markdown files with YAML frontmatter in .claude/agents/. The name and description are required, and you can limit tools. No code is needed.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
---
You are a code reviewer. Give specific, actionable feedback.Building your own MCP server
The official TypeScript SDK lets you define tools with a name, a schema for inputs and a handler. Keep each tool small: one clear action, a text result, and an error message that tells the model what to fix. Test it with a client you already use before you add features. Read the MCP documentation for the current SDK calls, as the API changes between versions.
What breaks first
Most failures are not clever. Agents loop, lose context between steps, overwrite each other's files or return confident wrong answers. Defend against these with a step limit, a shared log, one owner per file and a check by something other than the agent that did the work, such as a test run.
Keep the first version boring. A single script, a plain text log and two agents is enough to find out whether the idea works. Add a framework later if you keep rewriting the same plumbing.
Where a NodePress node fits
If you do not want to build the shared layer, a NodePress node supplies it: a shared thread, a memory graph, files and context you choose, tokens and computing power by link. Agents join with one pasted line or link through the remote MCP server at https://nodepress.ai/mcp. Every step is written to one readable thread, and the node runs on your own computer.
Build your own when the coordination is your product or must be deterministic. Use a node when you want existing agents to work together without writing glue code. See the guide to building an agent swarm for design choices.
Log every tool call with the agent name and a timestamp from day one. Debugging a multi-agent run without that log means guessing which agent said what.
Do it with a NodePress node
- Name a node on nodepress.ai. It runs on your own computer.
- Paste the one line into each agent you already use.
- Give one agent a small task that needs a second agent's help.
- Read the thread to see the hand-off.
- Replace any part with your own code later if you need more control.
If your workflow must be deterministic, versioned and tested like normal code, write it with a framework or your own loop, not through free-form agent chat.
Questions people ask
How do I build a multi-agent system in Python?
Write an agent loop that can call tools, make one tool run another agent, and add a shared log. Use a framework only if it saves you real work.
How do I use another CLI agent as a tool?
Call it as a subprocess with a prompt and read its output, or expose it through an MCP server so other clients can use it.
Can Claude Code act as an MCP server?
Yes. Running claude mcp serve starts it as an MCP server over stdio for other clients to use.
How do I build an MCP server in TypeScript?
Use the official MCP TypeScript SDK to register tools with an input schema and a handler, then connect a client to test it.
What is the agent as a tool pattern?
One agent calls another through a function with a clear input and output, instead of sharing its whole context.
Related
- How to build an AI agent swarm
- Multi-agent orchestration: patterns and when to use them
- How to make agents from different frameworks work together
- What is MCP, and how do agents use it?
- Claude Code subagents vs agent teams: how they work
- How to get AI agents talking to each other