Module 2: Host-Client-Server Architecture

Capsule description

In the previous module you understood what MCP is, the M×N problem it solves, and you used an existing MCP server in Claude Code. You saw that it works — you typed a request, Claude Code used a tool from the MCP server, and you received a response. But you didn't see how it works internally. That black box opens up in this module.

You're going to learn the 3-layer architecture that makes MCP possible: the Host (Claude Code), the Client (communication protocol), and the Server (your code). Each layer has distinct responsibilities, and understanding where one begins and another ends is the difference between following recipes and truly knowing how to build MCP servers.

By the end of this module, you'll be able to trace a complete request — from the moment you type something in Claude Code until the MCP server responds — identifying what happens in each layer, who initiates what, and where to look when something fails.

Where are we?

Context within the guide

This is Guide #5 of 11 in the Claude Code Agentic Development Path. You're in Module 2 of Phase 1: MCP Fundamentals.

Phase 1: MCP Fundamentals (Modules 1-3)
  ├── Module 1: What MCP Is and Why It Matters ✅ Completed
  ├── Module 2: Host-Client-Server Architecture ← You are here
  └── Module 3: Three Primitives — Resources, Tools, Prompts

Phase 2: Build MCP Servers (Modules 4-6)
  ├── Module 4: MCP Server in TypeScript
  ├── Module 5: MCP Server in Python
  └── Module 6: MCP Apps and Interactive UI

Phase 3: Production (Modules 7-8)
  ├── Module 7: Testing, Debugging, and Integration
  └── Module 8: Project — Real MCP Server

What you already know (Module 1)

From the previous module you bring these solid concepts:

✅ MCP is the "USB-C of AI" — a standard protocol for integrations
✅ The M×N problem and how MCP reduces it to M+N
✅ The current ecosystem: hosts (Claude Code, Cursor, Windsurf), servers (filesystem, memory, GitHub)
✅ You configured and used an MCP server (Filesystem) in Claude Code

What you add in this module

You go from "I know what it is and I know it works" to "I understand how it works internally":

Module 1: What MCP is
├── M×N problem → M+N solution
├── Ecosystem (hosts, servers)
└── First hands-on contact
    ↓
Module 2: How MCP works (this module)
├── 3-layer architecture
├── Connection lifecycle
└── Complete request-response flow
    ↓
Module 3: What an MCP Server exposes
├── Resources (data)
├── Tools (functions)
└── Prompts (templates)

The transition is direct: you already know that the MCP server responded to your request. Now you're going to see exactly how that request reached the server and how the response came back.

This module's key question

In module 1, when you asked Claude Code "list the files in my directory" and the Filesystem server responded, these things happened that you didn't see:

What actually happened?
│
├── Who decided to use the Filesystem server and not another?
├── How did Claude Code know which tools it had available?
├── In what format did your request travel to the server?
├── How did the server respond?
├── What happens if the server fails?
├── And what if there are 5 servers connected simultaneously?
└── Who handles the permissions for each operation?

Each of these questions has a precise answer in the architecture. By the end of the module, they'll all be obvious.

Module objective

By the end of this module, you'll be able to:

✅ Draw MCP's Host-Client-Server architecture without help
✅ Explain the specific role of each layer in one sentence
✅ Trace a complete request: user types → Host processes → Client sends → Server responds → response reaches the user
✅ Describe the connection lifecycle: initialize → discover capabilities → use → disconnect
✅ Explain how a Host handles multiple Clients (Claude Code connected to several MCP servers simultaneously)
✅ Identify which layer to look at when something fails

Module roadmap

Capsule	Topic	What you'll learn
02	The Host: the orchestrator	Claude Code as the Host — who initiates the connection, handles permissions, decides which tools to use
03	The Client: the connector	The communication protocol — connection lifecycle, capabilities negotiation, message format
04	The Server: the provider	Your code — exposing capabilities, responding to requests, handling state
05	Complete request-response flow	Trace a request end-to-end + mini-project: diagram your setup's architecture

Learning flow

First you'll understand the layer you already know as a user — the Host (Claude Code), the interface you use directly and who orchestrates everything (capsule 02). Then you'll go down a level to the Client, the invisible component that handles the communication between Host and Server (capsule 03). After that you'll reach the Server, where you'll eventually write your code (capsule 04). Finally, you'll bring the 3 layers together in a complete flow by tracing a request from start to finish (capsule 05).

The progression is top-down: Host → Client → Server → Complete flow. You start with the familiar (the interface you use) and go down toward what you'll build (the server).

Estimated time

Capsule	Content	Estimated time
02	Host + concepts + exercises	45-60 min
03	Client + protocol + exercises	60-75 min
04	Server + patterns + exercises	60-75 min
05	Complete flow + mini-project	60-90 min
Total	Full module	4-5 hours

Preview: the 3 layers in 30 seconds

Before going deep into each layer in the following capsules, here's the complete map:

┌─────────────────────────────────────────────────┐
│                  MCP HOST                        │
│              (Claude Code)                       │
│                                                  │
│  "I'm the application the user sees.             │
│   I decide which server to use for each request. │
│   I handle permissions and present results."     │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ MCP      │  │ MCP      │  │ MCP      │      │
│  │ Client 1 │  │ Client 2 │  │ Client 3 │      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       │              │              │            │
└───────┼──────────────┼──────────────┼────────────┘
        │              │              │
   JSON-RPC 2.0   JSON-RPC 2.0   JSON-RPC 2.0
   (via stdio)    (via stdio)    (via stdio)
        │              │              │
        ▼              ▼              ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │ MCP     │   │ MCP     │   │ MCP     │
   │ Server  │   │ Server  │   │ Server  │
   │ (files) │   │ (GitHub)│   │ (DB)    │
   └─────────┘   └─────────┘   └─────────┘

   "We expose    "We expose    "We expose
    tools for     tools for     tools for
    files"        repos/PRs"    queries"

Each layer has one clear job:

Layer	Role	In one sentence
Host	Orchestrates	Decides what to do, who does it, and presents the result
Client	Communicates	Translates the Host's decisions into the MCP protocol and sends them to the Server
Server	Provides	Executes the actual operation and returns the result

This table should be obvious by the end of the module. If after capsule 05 you can't fill it out from memory, go back and review.

Connection to the project

This module's mini-project

You're going to diagram the Host-Client-Server architecture of your current Claude Code setup. You'll take the MCP servers you configured in the previous module (at least the Filesystem server) and trace the complete flow of a request, identifying each layer and its responsibility.

Connection to the capstone project (Module 8)

In the final project you'll build a production-ready MCP server. Understanding the architecture now means that when you write your server in modules 4-6:

You'll know exactly what the Client expects from your Server
You'll understand how the Host discovers your Server's capabilities
You'll be able to diagnose problems by knowing which layer to look at
You'll design your Server knowing how it fits into the complete architecture

Without this module, you'd build servers by following recipes. With this module, you build servers understanding the system.

Prerequisites

For this module you need:

✅ To have completed Module 1 (MCP concepts, first contact)
✅ To have Claude Code installed with at least one MCP server configured
✅ Comfort reading architecture diagrams and data flows
✅ Basic familiarity with client-server concepts (HTTP, APIs)

You don't need: Knowledge of specific protocols, experience with JSON-RPC, or to have built servers before.

Boundaries: What is NOT covered in this module

❌ Code implementation — You're not going to write an MCP server yet (that comes in modules 4-6)
❌ The 3 primitives in detail — Resources, Tools, Prompts are covered in module 3
❌ Transports in depth — stdio vs HTTP/SSE are covered in modules 4 and 5
❌ Complete protocol specification — This module covers what you need to know as a developer, not the full technical spec
❌ Testing and debugging — Covered in module 7

This module is architectural and conceptual with practical examples. You're building the mental map that will guide all your future implementation.

Why the architecture matters

You could argue: "I already know MCP works, why do I need to know how it works internally?" Three concrete reasons:

1. Effective debugging

When your MCP server doesn't respond, you need to know where to look:

Is the Host not initiating the connection?   → Configuration problem
Is the Client not discovering capabilities?  → Initialization problem
Is the Server not responding to the request? → Problem in your code

Without understanding the architecture, every error is a mystery. With the architecture, every error has a location.

2. Informed design

When you design your MCP server, the decisions depend on understanding the layers:

Which capabilities to expose?  → Depends on what the Host can use
How to handle state?           → Depends on the Client's lifecycle
Which errors to return?        → Depends on what the Client expects

3. Communication with your team

When you explain your server to colleagues or write documentation, you need the correct vocabulary: "The Host discovers our capabilities in the initialization phase" is much more precise than "Claude Code connects and sees what it can do."

A quick example

Without understanding the architecture, this error is a mystery:

MCP Servers:
  filesystem: connected ✅
  github: disconnected ❌
  memory: connected ✅

With the architecture, you know exactly where to look:

github: disconnected

→ The Host launched the server's process (step 1: ✅)
→ The Client attempted the initialization handshake (step 2)
→ The Server didn't respond correctly (step 2: ❌)
→ Probable cause: GITHUB_TOKEN not configured
→ Solution: verify the server's environment variables

The other 2 servers aren't affected because each
Client-Server is an independent connection.

That's debugging with architecture. You went from "it doesn't work" to "I know exactly what to check."

Key module vocabulary

These are the terms you'll use throughout the module. You don't need to memorize them now — they'll settle in with each capsule:

Term	Meaning	First appearance
Host	Application the user uses (Claude Code)	Capsule 02
Client	Component inside the Host that speaks MCP with a Server	Capsule 03
Server	Your program that exposes capabilities	Capsule 04
Capabilities	What a Server can do (tools, resources, prompts)	Capsule 02
Initialize	Handshake between Client and Server when connecting	Capsule 03
Lifecycle	The phases of an MCP connection (init → operate → close)	Capsule 03
JSON-RPC	Message format that MCP uses	Capsule 03
Transport	How messages travel (stdio, HTTP)	Capsule 03
Handler	Function that processes a specific request	Capsule 04
inputSchema	Definition of a tool's parameters (JSON Schema)	Capsule 04

Signs of success

By the end of this module, you'll know you succeeded if:

✅ You can draw the 3-layer architecture with correct communication arrows
✅ You can explain in one sentence what each layer does: the Host orchestrates, the Client communicates, the Server provides
✅ You can trace the path of a request from the user to the server and back
✅ You can explain what happens when Claude Code initializes with an MCP server (the lifecycle)
✅ You can conceptually diagnose which layer a problem is in given an error
✅ You completed the diagram of your current Claude Code setup

The analogy we'll use in this module

In module 1 you used the USB-C analogy. In this module the analogy is a restaurant:

MCP Restaurant:

🧑‍💼 Host (Maître/Manager) = Claude Code
   → Receives the customer (user)
   → Decides which kitchen can satisfy the order
   → Manages permissions (can this customer order this dish?)
   → Coordinates everything

📋 Client (Waiter) = Communication protocol
   → Takes the order from the maître
   → Translates it into the kitchen's format
   → Brings it to the correct kitchen
   → Brings the response back

👨‍🍳 Server (Kitchen) = Your code
   → Receives the order from the waiter
   → Prepares it (executes the operation)
   → Returns the result

A restaurant can have MULTIPLE kitchens:
├── Italian kitchen (GitHub MCP Server)
├── Japanese kitchen (PostgreSQL MCP Server)
└── Mexican kitchen (Filesystem MCP Server)

The maître (Host) knows what each kitchen can serve.
Each kitchen has its own dedicated waiter (Client).

This analogy will accompany you through the next 4 capsules. Every time something isn't clear in the theory, go back to the restaurant.

The analogy mapped to a real request

Let's see how it translates to the concrete scenario you already experienced in module 1:

You ask Claude Code: "List the files in my project"

🧑‍💼 Maître (Host = Claude Code):
   "The customer wants to know what files they have.
    The filesystem kitchen (Filesystem Server) can solve this.
    I ask its waiter to carry the order."

📋 Waiter (Client):
   "Got it. I translate the order into the kitchen's format:
    tools/call → list_directory → /Users/dev/project
    I send it through the window (stdin)."

👨‍🍳 Kitchen (Server = Filesystem):
   "Order received. I execute the operation: I read the directory.
    Result: src/, package.json, README.md, test/
    I pass it back through the window (stdout)."

📋 Waiter (Client):
   "The kitchen responded. I deliver the result to the maître."

🧑‍💼 Maître (Host = Claude Code):
   "Got it. I present it to the customer in a readable way:
    'Your project has these files: src/, package.json,
     README.md, test/'"

That which seems instantaneous when you use Claude Code — that complete flow happens in milliseconds. But each step has an actor, a data format, and a point of possible failure.

Quick self-assessment before starting

Before entering the technical capsules, verify that you have the prerequisites from module 1. Answer mentally:

Can you explain what MCP is in one sentence? (Module 1, capsule 03)
Can you give an example of the M×N problem? (Module 1, capsule 02)
Do you have at least one MCP server configured in Claude Code? (Module 1, capsule 05)
Can you run /mcp in Claude Code and see a server "connected"? (Module 1, capsule 05)

If you answered yes to all 4, you're ready. If not, go back to module 1 before continuing. This module builds directly on those concepts.

Summary

This module covers the internal architecture of MCP — the 3 layers that make everything work
Progression: Host (orchestrator) → Client (connector) → Server (provider) → Complete flow
By the end you'll be able to trace a request from the user to the server and back
The mini-project is to diagram your current setup of Claude Code
Everything you learn here gives you the foundations to build MCP servers in modules 4-6
Without architecture, you follow recipes; with architecture, you understand the system

Additional resources

MCP Architecture Overview - Official architecture documentation
MCP Specification - Complete technical specification of the protocol
Introducing MCP (Anthropic Blog) - Design context and architectural decisions
MCP TypeScript SDK - SDK you'll use in module 4 (useful for seeing the architecture in code)
MCP Python SDK - SDK you'll use in module 5

Next capsule: The Host: the orchestrator — how Claude Code acts as an MCP Host, who initiates the connection, how permissions are handled, and why the Host is the central piece of the architecture.

← PreviousFirst Contact: Using an MCP Server in Claude Code Next →The Host: MCP's Orchestrator