Multi-Agent AI Collaboration Tutorial with MCP and Python [Lesson 6]

Learn to build multi-agent AI systems where specialized agents collaborate through MCP. Complete tutorial with working code for researcher and writer agents.

In Lesson 5, you built your first MCP server and watched Claude Desktop use your custom tool to read local files. That was powerful. You gave an AI model the ability to access your data safely through a tool you control.

But here’s where things get really interesting:

What if multiple AI agents could work together, each focusing on what they do best, sharing information through the same MCP server?

That’s exactly what we’re building today.

In this lesson, you’ll create a multi-agent workflow where one agent researches a topic and another agent writes a polished document based on that research. They’ll collaborate through a shared MCP server, demonstrating how AI agents can work like specialized team members in a company.

Multiple AI agents can work like specialized team members, each focusing on what they do best while sharing information through MCP.

---

MCP Masterclass - Full Course Index

• Lesson 1. What is MCP . Model Context Protocol?

• Lesson 2. Why MCP Was Created?

• Lesson 3. How MCP Actually Works . Hosts, Clients, and Servers

• Lesson 4. The Three Superpowers of MCP . Tools, Resources, and Prompts

• Lesson 5. Build an MCP Server in 30 Minutes

• Lesson 6. Multi-Agent AI Collaboration Tutorial ← You are here

• Lesson 7. Give Your AI Agents Memory

• Lesson 8. Building AI Agents That Learn From Experience

---

Think Company Departments

Imagine you work at a growing company with two departments:

The Research Department spends their days gathering information, analyzing data, and organizing findings. They’re experts at digging deep, fact-checking, and creating comprehensive reports. When they finish their work, they save it in the company’s shared filing system.

The Writing Department takes those research reports and transforms them into polished documents like blog posts, white papers, presentations. They’re experts at clear communication, storytelling, and making complex topics accessible. They pull research from the shared filing system whenever they need it.

Neither department does the other’s job. The researchers don’t write the final documents, and the writers don’t spend days gathering raw data. Each team focuses on their specialty, and they collaborate through the shared filing system that connects them.

Here’s what makes this powerful:

You can hire more specialists as you grow.

• Need a fact-checker? Add a Quality Assurance Department.

• Need visuals? Add a Design Department.

Each new team plugs into the same shared system and immediately starts contributing their specialized skills.

The filing system (your MCP server) stays consistent. Everyone knows how to save their work and read others’ work. There’s no confusion, no duplicate systems, no wasted effort.

That’s exactly how multi-agent collaboration works with MCP.

Each AI agent is like a specialized department. The MCP server is the shared filing system. Each agent focuses on what it does best, saves its work through MCP tools, and reads others’ work through those same tools. You orchestrate the collaboration by deciding which agent handles which task.

---

Let’s break down how we’ll build this multi-agent system step by step.

Part 0: Set Up Your Environment

Before we write any code, let’s prepare a clean workspace. If you are coming from Lesson 5, you can skip some of these steps.

Step 0.1: Create a Project Folder

1. Create a new folder on your computer

2. Name it: mcp_lesson_6

3. Open this folder in your code editor (VS Code, Cursor, or PyCharm)

Step 0.2: Create a Python Virtual Environment

We use a virtual environment so this project doesn’t interfere with anything else on your machine.

If you use macOS or Linux, run these commands in a terminal inside the folder:

python3 -m venv .venv 
source .venv/bin/activate

If you use Windows, run:

py -m venv .venv
.venv\Scripts\activate

After this, you should see something like:

(.venv) yourname@mcp_lesson_6 %

That means the virtual environment is active.

If you want to leave it later, type:

deactivate

Step 0.3: Install the Required Packages

If you are coming from Lesson 5, you can skip this step. Otherwise, run this inside the same terminal while the environment is active:

pip install mcp

This installs the official Python SDK for MCP which has everything you need to build an MCP server.

If pip is not found, reinstall Python from the official site and make sure to check “Add Python to PATH” during installation.

Step 0.4: Install Claude Desktop

If you are coming from Lesson 5, you can skip this step. Otherwise continue.

Claude Desktop will act as your MCP Host, the application that connects to your server and lets the AI model use your tools.

1. Go to claude.ai/download

2. Download Claude Desktop for your operating system (macOS or Windows)

3. Install it and sign in with your Claude account

Note: You need a Claude account (free or paid) to use Claude Desktop.

Step 0.5: Check That Everything Is Ready

If you are coming from Lesson 5, you can skip this step. Otherwise continue.

Create a new file in the project folder called:

check_setup.py

Paste this code:

# This script verifies that the MCP SDK is installed correctly

try:
    from mcp.server import Server
    from mcp.server.stdio import stdio_server
    from mcp.types import Tool, TextContent
    
    print(”✓ MCP SDK is installed correctly!”)
    print(”✓ All required components are available”)
    print(”\nYou’re ready to build your first MCP server!”)
    
except ImportError as e:
    print(”✗ MCP SDK installation issue detected:”)
    print(f”  Error: {e}”)
    print(”\nPlease run: pip install mcp”)

Run it:

python check_setup.py

---

Part 1: Understanding the Collaboration Pattern

In Lesson 5, you had one conversation with Claude Desktop. Claude used your MCP server to read files. Simple and effective.

For multi-agent collaboration, you’ll have multiple separate conversations with Claude Desktop. You can think of each conversation as a different specialized agent. The key insight is that all these conversations can connect to the same MCP server.

Here’s the flow:

Step 1: You open Conversation 1 (Researcher Agent) and say: “Research how to choose a programming language and save your findings.”

The Researcher Agent thinks through the topic, organizes information, and uses the save_research tool from your MCP server to save its findings to a file.

Step 2: You open Conversation 2 (Writer Agent) and say: “Read the research findings and write a clear article about choosing a programming language.”

The Writer Agent uses the read_research tool to access what the Researcher saved, then writes a polished document and uses the save_draft tool to save it.

Step 3: You read the final draft and see how two specialized agents collaborated to create something better than either could have done alone.

The magic: Both agents used the same MCP server. The server acted as the shared workspace where they exchanged information. You didn’t need complex coordination code rather just clear instructions to each agent about their role.

---

Part 2: Building the Shared MCP Server

Your MCP server for this lesson needs three tools:

Tool 1: save_research

• Takes research content as input

• Saves it to research_findings.txt

• Confirms it was saved successfully

Tool 2: read_research

• Reads the content from research_findings.txt

• Returns it so an agent can use it

• Reports an error if the file doesn’t exist yet

Tool 3: save_draft

• Takes final document content as input

• Saves it to final_draft.txt

• Confirms it was saved successfully

These three tools create a simple but powerful collaboration pipeline:

research in → research stored → research read → draft out

The pattern is identical to Lesson 5. You’re just adding more tools to the same server structure. Each tool follows the same principles: accept input, do something with it, return a result.

Step 2.1: Write your MCP Server

Now let’s create the server that exposes the three tools save_research, read_research and save_draft.

Create a file called:

server.py

Paste this code:

import asyncio
from pathlib import Path
from mcp.server.models import InitializationOptions
from mcp.server import NotificationOptions, Server
from mcp.server.stdio import stdio_server
from mcp.types import TextContent, Tool

# Create the server instance with a descriptive name
server = Server(”collaboration-hub”)


@server.list_tools()
async def handle_list_tools() -> list[Tool]:
    “”“
    Define all tools this server provides.
    
    Each tool represents a capability that AI agents can use to collaborate.
    Notice how all three tools follow the same pattern, just with different
    purposes and file targets.
    “”“
    return [
        Tool(
            name=”save_research”,
            description=”Save research findings to a file for other agents to read”,
            inputSchema={
                “type”: “object”,
                “properties”: {
                    “content”: {
                        “type”: “string”,
                        “description”: “The research findings to save”
                    }
                },
                “required”: [”content”]
            }
        ),
        Tool(
            name=”read_research”,
            description=”Read research findings saved by the Researcher agent”,
            inputSchema={
                “type”: “object”,
                “properties”: {},
                “required”: []
            }
        ),
        Tool(
            name=”save_draft”,
            description=”Save a final draft document”,
            inputSchema={
                “type”: “object”,
                “properties”: {
                    “content”: {
                        “type”: “string”,
                        “description”: “The final draft content to save”
                    }
                },
                “required”: [”content”]
            }
        )
    ]


@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> list[TextContent]:
    “”“
    Execute the requested tool.
    
    This handler routes tool calls to the appropriate logic based on the
    tool name. Each tool follows the same pattern: validate, execute, return.
    “”“
    
    # Get the base directory where this server lives
    base_dir = Path(__file__).parent
    
    # Route to the appropriate tool handler
    if name == “save_research”:
        return await save_research_handler(arguments, base_dir)
    elif name == “read_research”:
        return await read_research_handler(base_dir)
    elif name == “save_draft”:
        return await save_draft_handler(arguments, base_dir)
    else:
        raise ValueError(f”Unknown tool: {name}”)


async def save_research_handler(arguments: dict, base_dir: Path) -> list[TextContent]:
    “”“
    Save research findings to a file.
    
    The Researcher agent uses this tool to store its work so other agents
    can access it later.
    “”“
    content = arguments.get(”content”)
    if not content:
        return [TextContent(
            type=”text”,
            text=”Error: No content provided to save”
        )]
    
    # Save to research_findings.txt
    file_path = base_dir / “research_findings.txt”
    
    try:
        file_path.write_text(content, encoding=”utf-8”)
        return [TextContent(
            type=”text”,
            text=f”Research findings saved successfully to {file_path.name}”
        )]
    except Exception as e:
        return [TextContent(
            type=”text”,
            text=f”Error saving research: {str(e)}”
        )]


async def read_research_handler(base_dir: Path) -> list[TextContent]:
    “”“
    Read research findings from the file.
    
    Any agent can use this tool to access what the Researcher saved.
    This is how agents share information.
    “”“
    file_path = base_dir / “research_findings.txt”
    
    if not file_path.exists():
        return [TextContent(
            type=”text”,
            text=”No research findings found. The Researcher agent needs to save research first using the save_research tool.”
        )]
    
    try:
        content = file_path.read_text(encoding=”utf-8”)
        return [TextContent(
            type=”text”,
            text=content
        )]
    except Exception as e:
        return [TextContent(
            type=”text”,
            text=f”Error reading research: {str(e)}”
        )]


async def save_draft_handler(arguments: dict, base_dir: Path) -> list[TextContent]:
    “”“
    Save the final draft document.
    
    The Writer agent uses this tool to store the finished article.
    “”“
    content = arguments.get(”content”)
    if not content:
        return [TextContent(
            type=”text”,
            text=”Error: No content provided to save”
        )]
    
    # Save to final_draft.txt
    file_path = base_dir / “final_draft.txt”
    
    try:
        file_path.write_text(content, encoding=”utf-8”)
        return [TextContent(
            type=”text”,
            text=f”Final draft saved successfully to {file_path.name}”
        )]
    except Exception as e:
        return [TextContent(
            type=”text”,
            text=f”Error saving draft: {str(e)}”
        )]


async def main():
    “”“
    Start the MCP server and run it indefinitely.
    
    This is identical to Lesson 5. The only difference is we have more tools.
    “”“
    async with stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name=”collaboration-hub”,
                server_version=”1.0.0”,
                capabilities=server.get_capabilities(
                    notification_options=NotificationOptions(),
                    experimental_capabilities={},
                )
            )
        )


if __name__ == “__main__”:
    asyncio.run(main())

Step 2.2: Configure Claude Desktop

You need to update your Claude Desktop configuration to include this new server. The server has a different name (collaboration-hub) and different tools than the Lesson 5 server.

Get Python Path

We need the full path to your Python executable inside the virtual environment.

On macOS/Linux, run:

which python

On Windows, run:

where python

Copy the full path. It may look something like:

• macOS/Linux: /Users/yourname/mcp_lesson_6/.venv/bin/python

• Windows: C:\Users\yourname\mcp_lesson_6\.venv\Scripts\python.exe

Get the full path to your server.py file.

Easy way:

• In VS Code/Cursor: Right-click server.py → Copy Path

• Or manually combine your project folder path + /server.py

Example:

• macOS/Linux: /Users/yourname/mcp_lesson_6/server.py

• Windows: C:\Users\yourname\mcp_lesson_6\server.py

Edit Claude Desktop’s configuration

Open Claude Desktop, go to Settings, Developer tab, click Edit Config.

Add this new server to your configuration (keep your existing note-reader server from Lesson 5):

{
  “mcpServers”: {
    “note-reader”: {
      “command”: “/FULL/PATH/TO/lesson-05/.venv/bin/python”,
      “args”: [”/FULL/PATH/TO/lesson-05/server.py”]
    },
    “collaboration-hub”: {
      “command”: “/FULL/PATH/TO/lesson-06/.venv/bin/python”,
      “args”: [”/FULL/PATH/TO/lesson-06/server.py”]
    }
  }
}

Replace the paths with your actual paths. On Windows, remember to use double backslashes.

Save the file and completely quit and restart Claude Desktop.

After restarting Claude Desktop, verify you see the collaboration-hub server with three tools: save_research, read_research, and save_draft. Now let’s run the collaboration workflow.

---

Part 3: Setting Up the Researcher Agent

The Researcher Agent is simply a conversation in Claude Desktop where you give Claude the role of a researcher. You might say:

“You are a research specialist. I need you to research the topic: ‘How to choose a programming language.’ Gather key considerations like project type, performance needs, learning curve, community support, and job market. Organize your findings clearly, then use the save_research tool to save them.”

Claude, acting as the Researcher, will think through the topic and use your save_research tool to store its findings. You’ll see it ask for permission to use the tool, you’ll click Allow, and the research gets saved to your local filesystem.

The Researcher doesn’t worry about writing a polished article. It focuses purely on gathering and organizing information which is its specialty.

Part 4: Setting Up the Writer Agent

The Writer Agent is a separate conversation where you give Claude a different role. You might say:

“You are a professional writer. Read the research findings about choosing a programming language using the read_research tool, then write a clear, engaging article for beginners. Make it practical and easy to understand. When you’re done, save it using the save_draft tool.”

Claude, now acting as the Writer, will use your read_research tool to access what the Researcher saved. It reads that content, processes it, writes a polished article, and uses your save_draft tool to save the final document.

The Writer doesn’t do the research. It trusts that the Researcher did that job well. The Writer focuses purely on clear communication which is its specialty.

Part 5: Watching Them Collaborate

Here’s what the complete workflow looks like:

You → Researcher Agent: “Research how to choose a programming language and save your findings.”

Researcher Agent:

• Thinks through the topic

• Organizes key points

• Uses save_research tool

• Confirms: “I’ve saved comprehensive research findings about choosing programming languages.”

You → Writer Agent: “Read the research and write an article about it.”

Writer Agent:

• Uses read_research tool

• Reads what Researcher saved

• Writes polished article

• Uses save_draft tool

• Confirms: “I’ve written and saved an article based on the research.”

You: Open final_draft.txt on your computer and read the result. You now have a well-researched, well-written article created through agent collaboration.

What just happened:

Two specialized agents, working in their areas of expertise, collaborated through your MCP server to create something neither could have done as well alone.

• The Researcher focused on depth and accuracy.

• The Writer focused on clarity and readability.

• The MCP server connected them seamlessly.

---

Why It Matters

You just built something that most people think requires complex orchestration frameworks or expensive enterprise AI tools. But you did it with simple, clean patterns that you already understood from Lesson 5.

Other real-world applications of this pattern:

Content Creation Pipeline

A research agent gathers information from multiple sources, a writing agent creates the draft, an editing agent polishes it, and a fact-checking agent verifies claims. Each agent specializes, and they all share work through MCP.

Business Analysis Workflow

A data agent pulls metrics from databases, an analysis agent identifies trends, a visualization agent creates charts, and a reporting agent writes executive summaries. Each focuses on their strength.

Customer Support System

A triage agent categorizes incoming requests, a knowledge agent searches documentation, a response agent drafts replies, and a quality agent reviews before sending. Specialized roles, shared coordination.

Development Workflow

A planning agent breaks down features into tasks, a coding agent implements them, a testing agent validates the code, and a documentation agent writes guides. Each agent contributes expertise.

---

The pattern scales infinitely.

Need a new capability? Add a new specialized agent that connects to the same MCP server. The existing agents don’t change. The server stays consistent. You just orchestrate the workflow by directing which agent handles which task.

This is the foundation for autonomous systems.

Right now, you’re manually directing each agent (”Researcher, do this” then “Writer, do that”).

In later lessons, you’ll learn how to let agents decide when to hand off work to each other, how to add memory so they learn from past collaborations, and how to create loops where agents work continuously without your constant input.

But it all starts with this simple pattern: specialized agents, shared MCP server, clear roles.

---

Mini Exercise

Now that you have a working multi-agent system, try these experiments:

Experiment 1: Different Research Topic

Ask your Researcher Agent to research a completely different topic, like “The benefits of morning routines” or “How electric cars work.” Then have your Writer Agent create an article from that research. The same tools work for any content.

Experiment 2: Add Quality Control

Open a third conversation (Editor Agent) and say: “You are an editor. Read the draft using the read_research tool (it will read from final_draft.txt if you modify the code slightly), identify any weak areas, and suggest improvements.” Now you have a three-agent pipeline.

Experiment 3: Specialized Instructions

Give your Researcher Agent more specific instructions: “Focus only on technical accuracy, cite sources, use bullet points.” Give your Writer Agent different instructions: “Write in a conversational tone, use examples, make it under 500 words.” See how specialization creates better results.

Experiment 4: Reverse the Roles

Ask your Writer Agent to create an outline for an article, then ask your Researcher Agent to fill in detailed information for each section. Sometimes the writing structure comes before the research. Your MCP system handles both workflows.

---

Key Takeaways

• Multi-agent collaboration means specialized AI agents working together through shared MCP tools

• Each agent focuses on what it does best—research, writing, editing, analysis, etc.

• The MCP server acts as the shared workspace where agents exchange information

• You orchestrate collaboration by giving each agent clear instructions and roles

• The same patterns from Lesson 5 scale to any number of agents with any specializations

• This pattern is the foundation for autonomous systems you’ll build in later lessons

• Real-world applications include content pipelines, business analysis, customer support, and development workflows

---

Your Code Repository

All the working code for this lesson is available in the MCP Masterclass GitHub repository in the lesson-06 folder. You’ll find:

• Complete MCP server with all three tools

• Example conversation templates for Researcher and Writer agents

• Sample output files showing what the collaboration produces

• Troubleshooting guide for common issues

Clone the repository to follow along with working examples, or use it as a reference if you get stuck. The README in the lesson-06 folder has complete setup instructions.

---

Next Lesson

In Lesson 7, we’ll add something powerful to this multi-agent system: shared memory. Right now, your agents start fresh every time you talk to them. They can read files you explicitly ask them to read, but they don’t remember previous conversations or learn from past work.

Next lesson, you’ll give your agents the ability to remember outcomes, store insights across sessions, and build on previous collaborations. That’s when simple collaboration becomes true teamwork.

---

PS: Next time you see a well-researched article or comprehensive report, remember that it probably involved multiple specialists or teams working together. With MCP, you can create that same specialized collaboration with AI agents, each contributing their expertise to produce better results than any single agent could achieve alone. That’s the power of multi-agent systems.

---