AI Engineering: Agents and Applications › The Model Context Protocol › Day 299

Day 299: Building an MCP Client

Day 299 of 365 — Building an MCP Client

Build an autonomous AI agent that acts as an MCP Host Client: dynamically discover tools from multiple MCP servers over stdio, convert schemas into LLM function calls, and dispatch actions in a ReAct loop.

Course
AI Engineering: Agents and Applications
Category
The Model Context Protocol
Reading time
≈ 35 min
Practical time
≈ 50 min
Lesson duration
1h 25m
Last verified
2026-08-30

Hands-on lab for this lesson

Lab files on GitHub: https://github.com/ai-roadmap-365/ai-roadmap-365.github.io/tree/main/labs/sections/ai-engineering/day-299-building-an-mcp-client

  1. Get the hands-on files. Clone the labs repository once (you can reuse this clone for every lesson). This works on macOS, Linux, and Windows (PowerShell or WSL):
    git clone https://github.com/ai-roadmap-365/ai-roadmap-365.github.io.git
    cd ai-roadmap-365.github.io
  2. Open this lesson's lab. Move into the directory for this specific day. Every lab lives at the same predictable path — section / subsection / week / day:
    cd labs/sections/ai-engineering/day-299-building-an-mcp-client
  3. Read the lab guide. Open `README.md` in that directory. It lists the exact commands, what each does, the expected output, and how to check your work — read it before running anything.
  4. Run it and check your work. Follow the README's "How to run" section: run the example first to see the finished result, then complete the numbered exercises in `starter/`, then run the tests. The tests pass (exit 0) only when your work is correct.
    bash tests/run_tests.sh   # or the test command named in the lab README

You can also open the lab as a local page (works offline, shows the file tree and expected output).

Learning objectives

By the end of this lesson you will be able to:

Prerequisites

Why this matters

While many developers use standard desktop AI applications (like Claude Desktop or Cursor) as their MCP client, production AI engineering frequently requires building custom MCP host clients. When building autonomous backend agents, CLI development assistants, CI/CD automation bots, or domain-specific research pipelines, your Python application itself must act as the MCP client: spawning child server processes, aggregating tool schemas from diverse backends, injecting them into model prompts, and dispatching tool executions across standard I/O pipes.

Building an MCP client gives you complete programmatic control over the execution lifecycle. You decide how many servers to run concurrently, how tool routing tables are maintained, how rate limits and timeout errors are handled, and how observations are fed back into autonomous reasoning loops (like ReAct).

Mastering MCP client development transforms you from a passive consumer of AI tools into an architect capable of building modular, multi-server enterprise agent systems.

MCP Client Multi Server Orchestration Architecture diagram showing LLM Core, Unified Tool Registry, and multi-server stdio connections to Database, Git, and Web servers

The idea in plain language

Diagram: the four responsibilities of an MCP host client

Think of an MCP Client like the operating system’s device manager inside a computer:

The AI model doesn’t need to know operating system internals; the MCP client orchestrates everything behind the scenes.

Historical background

Diagram: the progression from hardcoded tool classes to multi-server MCP clients

The evolution of agent-tool client architecture developed across three major milestones:

1. Hardcoded API Clients (2022–2023)

Early LangChain and AutoGen agents used hardcoded Python tool wrapper classes. If you wanted to add a new tool, you had to write a Python class, instantiate it in memory, and import it into the agent script. This tightly coupled tools to the host process.

2. OpenAI Function Calling Clients (2023–2024)

OpenAI introduced client-side function calling schemas. Clients converted functions into JSON schemas, sent them in the tools array of the API request, and parsed tool_calls in the response.

3. Open Multi-Server MCP Clients (2024–Present)

The Model Context Protocol standardized client-server tool aggregation. Modern MCP clients connect to multiple independent server processes across stdio and SSE, dynamically merging their tool definitions into a single runtime toolset.

What it is — and what it is not

Let us define what an MCP Client is:

What an MCP Client Is:

What an MCP Client Is Not:

Diagram: an MCP client compared with an MCP server and a foundation model

+-------------------------------------------------------------------------------+
|                       MCP CLIENT RESPONSIBILITY MATRIX                        |
+-------------------+-----------------------+-----------------------------------+
| Lifecycle Stage   | Action Required       | Wire Protocol Method              |
+-------------------+-----------------------+-----------------------------------+
| 1. Startup        | Spawn child process   | `subprocess.Popen`                |
| 2. Handshake      | Negotiate version     | `initialize` request              |
| 3. Confirmation   | Acknowledge init      | `notifications/initialized`       |
| 4. Discovery      | Retrieve tool schemas | `tools/list` request              |
| 5. Reasoning      | Pass tools to LLM     | Chat Completion API call          |
| 6. Execution      | Route tool call       | `tools/call` request              |
| 7. Teardown       | Terminate subprocess  | SIGTERM / Pipe close              |
+-------------------+-----------------------+-----------------------------------+

Why it was created and what problems it solves

Building custom MCP clients solves four fundamental architectural problems:

1. Decoupled Tool Infrastructure

You can update, patch, or replace your PostgreSQL MCP server without touching your AI agent’s reasoning code.

2. Multi-Language Tool Aggregation

A Python agent client can seamlessly invoke tools written in TypeScript, Go, or Rust running inside child MCP subprocesses.

3. Enterprise Safety & Audit Logging

The client acts as a security firewall between the LLM and the server, logging every payload, inspecting arguments, and enforcing approval gates before dispatch.

4. Dynamic Capability Expansion

An agent can dynamically discover new tools at runtime based on user configuration without code recompilation.

How it works

Diagram: the four architectural benefits of building a custom MCP client

Deep Dive: Building Asynchronous Multi-Server Connection Pools

Diagram: the requirements of an asynchronous multi-server connection pool

When an autonomous agent connects to 5+ MCP servers simultaneously, managing individual synchronous subprocess threads causes latency bottlenecks and race conditions. Modern production clients implement Asynchronous Connection Pools using Python’s asyncio.subprocess and asyncio.StreamReader:

import asyncio
import json
from typing import Dict, Any, List

class AsyncMCPConnection:
    def __init__(self, name: str, command: str, args: List[str]):
        self.name = name
        self.command = command
        self.args = args
        self.process: asyncio.subprocess.Process = None
        self.req_id = 0
        self.lock = asyncio.Lock()
        
    async def start(self):
        self.process = await asyncio.create_subprocess_exec(
            self.command, *self.args,
            stdin=asyncio.subprocess.PIPE,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE
        )
        # Perform async handshake
        await self.send_request("initialize", {"protocolVersion": "2024-11-05"})
        
    async def send_request(self, method: str, params: Dict[str, Any] = None) -> Dict[str, Any]:
        async with self.lock:
            self.req_id += 1
            payload = {"jsonrpc": "2.0", "id": self.req_id, "method": method}
            if params is not None:
                payload["params"] = params
            data = (json.dumps(payload) + "\n").encode("utf-8")
            self.process.stdin.write(data)
            await self.process.stdin.drain()
            
            line = await self.process.stdout.readline()
            return json.loads(line.decode("utf-8").strip())

class ParallelMCPClientPool:
    def __init__(self):
        self.connections: Dict[str, AsyncMCPConnection] = {}
        
    async def call_tools_in_parallel(self, tool_invocations: List[dict]) -> List[dict]:
        # Execute tool calls across distinct servers simultaneously using asyncio.gather
        tasks = []
        for inv in tool_invocations:
            conn = self.connections[inv["server_name"]]
            tasks.append(conn.send_request("tools/call", {"name": inv["tool_name"], "arguments": inv["arguments"]}))
        return await asyncio.gather(*tasks)

Handling Server Crashes and Subprocess Respawning

If an external MCP server crashes (due to segmentation fault, OOM killer, or unhandled exception), a resilient client must:

  1. Detect closed pipes (EOFError on readline()).
  2. Log the crash event and captured stderr buffer.
  3. Automatically respawn the subprocess up to max_retries (e.g. 3 attempts with exponential backoff).
  4. Inform the reasoning loop with a descriptive observation: "System Notification: Server 'git-mcp' was restarted after a crash. Retrying tool call.".

Let us trace the complete execution flow of an MCP Client running an autonomous ReAct loop:

[User Task Request: "Find inactive users in DB and summarize"]
                         │
                         ▼
        [MCP Client: Unified Tool Registry]
     Discovers: {"sql_query": Server1, "send_email": Server2}
                         │
                         ▼
             [LLM Model Reasoning Turn]
      Thought: "I need to query the database for inactive users."
      Action: sql_query(query="SELECT * FROM users WHERE active=false")
                         │
                         ▼
           [MCP Client Routing & Dispatch]
      Routes to Server 1 -> sends tools/call over stdio
                         │
                         ▼
            [Server 1 Returns Result]
      Content: [{"type": "text", "text": "Found 3 users: Bob, Charlie, Dan"}]
                         │
                         ▼
          [MCP Client Injects Observation]
      Observation: "Found 3 users: Bob, Charlie, Dan"
                         │
                         ▼
             [LLM Next Reasoning Turn]
      Thought: "I have the data. I will emit the final answer."
      Final Answer: "There are 3 inactive users: Bob, Charlie, and Dan."

MCP Client ReAct Agent Loop Flow showing model reasoning turn, tool selection, MCP JSON-RPC dispatch, and observation integration

An everyday analogy

Diagram: a general contractor coordinating subcontractors as an analogy for an MCP client

Think of an MCP Client like a general contractor managing specialized subcontractors on a construction site:

Examples in practice

Graceful Degradation and Dynamic Tool Pruning

Diagram: sending every tool schema compared with semantically pruning them

When connecting an autonomous agent to a large server pool exposing 50+ total tools, passing the complete tool schema catalog on every LLM call consumes thousands of prompt tokens and degrades model reasoning accuracy (a phenomenon known as tool distraction).

A production MCP client implements Semantic Tool Retrieval & Dynamic Pruning:

  1. Tool Schema Embedding: At client startup, embed each tool name and description using a lightweight local embedding model (e.g. all-MiniLM-L6-v2).
  2. Contextual Retrieval: On each user turn, perform cosine similarity between the user’s prompt and the tool vector catalog.
  3. Top-K Injection: Dynamically pass only the top 5–8 most relevant tool schemas in the model API call.
  4. Fallback Recovery: If the model’s response indicates a missing capability, expand the tool window to include secondary server tools.

This optimization reduces per-turn input token costs by up to 70% while improving the model’s tool selection accuracy.

Let us build a complete Python Autonomous Agent with Multi-Server MCP Client Integration:

import json
import subprocess
import os
from typing import Dict, Any, List, Optional

class MCPClientConnection:
    def __init__(self, name: str, command: str, args: List[str]):
        self.name = name
        self.process = subprocess.Popen(
            [command] + args,
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=1
        )
        self.req_id = 0
        self._initialize()
        
    def _send(self, method: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
        self.req_id += 1
        payload = {"jsonrpc": "2.0", "id": self.req_id, "method": method}
        if params is not None:
            payload["params"] = params
        self.process.stdin.write(json.dumps(payload) + "
")
        self.process.stdin.flush()
        line = self.process.stdout.readline()
        return json.loads(line.strip())
        
    def _initialize(self):
        self._send("initialize", {"protocolVersion": "2024-11-05"})
        # Send initialized notification
        notif = {"jsonrpc": "2.0", "method": "notifications/initialized"}
        self.process.stdin.write(json.dumps(notif) + "
")
        self.process.stdin.flush()
        
    def list_tools(self) -> List[Dict[str, Any]]:
        res = self._send("tools/list")
        return res.get("result", {}).get("tools", [])
        
    def call_tool(self, name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
        res = self._send("tools/call", {"name": name, "arguments": arguments})
        return res.get("result", {})
        
    def close(self):
        if self.process.poll() is None:
            self.process.terminate()
            self.process.wait()

class AutonomousMCPAgent:
    def __init__(self):
        self.servers: Dict[str, MCPClientConnection] = {}
        self.tool_routing: Dict[str, MCPClientConnection] = {} # tool_name -> connection
        self.unified_tools: List[Dict[str, Any]] = []
        
    def connect_server(self, name: str, command: str, args: List[str]):
        conn = MCPClientConnection(name, command, args)
        self.servers[name] = conn
        tools = conn.list_tools()
        for t in tools:
            self.tool_routing[t["name"]] = conn
            self.unified_tools.append(t)
            
    def execute_tool(self, tool_name: str, arguments: Dict[str, Any]) -> str:
        if tool_name not in self.tool_routing:
            return f"Error: Tool '{tool_name}' not found on any connected MCP server."
        conn = self.tool_routing[tool_name]
        result = conn.call_tool(tool_name, arguments)
        content_list = result.get("content", [])
        return "
".join([c.get("text", "") for c in content_list])
        
    def close_all(self):
        for conn in self.servers.values():
            conn.close()

Implications: security, privacy, performance, scalability, and cost

Diagram: the file descriptor, naming and cancellation hazards of an MCP client

Resilient Tool Execution and Dynamic Schema Translation

Diagram: how a schema translation layer decouples an agent from provider SDKs

When routing tool calls across multiple distinct AI model providers (OpenAI, Anthropic Claude, Google Gemini, local Ollama), each API expects slightly different tool schema wrappers. A robust MCP client implements a universal schema transformer:

def mcp_to_openai_tool(mcp_tool: dict) -> dict:
    '''Convert an MCP tool definition into OpenAI function calling format.'''
    return {
        "type": "function",
        "function": {
            "name": mcp_tool["name"],
            "description": mcp_tool.get("description", ""),
            "parameters": mcp_tool.get("inputSchema", {"type": "object", "properties": {}})
        }
    }

def mcp_to_anthropic_tool(mcp_tool: dict) -> dict:
    '''Convert an MCP tool definition into Anthropic Claude tool format.'''
    return {
        "name": mcp_tool["name"],
        "description": mcp_tool.get("description", ""),
        "input_schema": mcp_tool.get("inputSchema", {"type": "object", "properties": {}})
    }

This translation layer decouples your autonomous agent logic from foundation model SDK changes. Whether your agent uses Claude 3.5 Sonnet or Gemini 1.5 Pro, the underlying MCP servers execute identically.

1. Subprocess Pipe Exhaustion

Operating systems enforce limits on the maximum number of open file descriptors. A client connecting to dozens of servers must manage connection pools and close unused pipes cleanly.

2. Tool Name Collision

If Server A and Server B both expose a tool named search, the client must implement namespacing (e.g. db__search vs web__search) to prevent routing ambiguity.

Alternatives: free, open source, and commercial

Client ArchitectureImplementationRouting ModelBest Suited For
Custom Python MCP ClientDirect Subprocess stdioIn-Memory RegistryBackend autonomous agents
Claude DesktopNative Electron AppUI ManagedPersonal interactive chat
Cursor / Zed IDERust / C++ Host EngineEditor ManagedAI Coding assistants
LangChain MCP AdapterPython Framework PluginLangChain ToolsLangGraph state graph pipelines
+-----------------------+-----------------------+-----------------------+
| Dimension             | MCP Server            | MCP Client            |
+-----------------------+-----------------------+-----------------------+
| Role                  | Service Provider      | Service Consumer      |
| IO Streams            | Reads stdin/Writes out| Writes in/Reads stdout|
| State Responsibility  | Tool execution logic  | Multi-server routing  |
| Initiates Connections | Passive (Spawned)     | Active (Spawner)      |
+-----------------------+-----------------------+-----------------------+

When to use it — and when not to

Diagram: when building a custom MCP client is warranted

Protocol Timeout and Cancellation Handling

In production agent deployments, tools that interact with slow external systems (such as large database migrations or web crawlers) may take tens of seconds to complete. If a user cancels an ongoing request in the UI, or if a tool exceeds an execution deadline, the client must transmit a JSON-RPC cancellation notice:

{
  "jsonrpc": "2.0",
  "method": "notifications/cancelled",
  "params": {
    "requestId": 101,
    "reason": "User aborted execution in web UI"
  }
}

The child MCP server intercepts the cancellation notification, terminates the active worker thread or network request, and releases allocated system resources immediately, preventing server worker starvation.

Choose Building an MCP Client when:

Do NOT build a custom MCP client when:

The AI connection

Knowledge check

  1. What is the function of the unified tool registry in an MCP client? To aggregate tool definitions from all connected servers and map tool names to server connections.
  2. How does the client execute a tool on a child process? By sending a tools/call JSON-RPC message over the server’s stdin pipe and reading the response from stdout.
  3. What happens during capability negotiation? The client and server exchange supported protocol versions and feature sets via initialize.

Hands-on exercise

In this lab, you will implement an Autonomous MCP Client with Multi-Server Management in Python. Your implementation will:

  1. Construct an MCPClientConnection manager handling subprocess handshakes.
  2. Build an AutonomousMCPAgent aggregating tools across multiple mock servers.
  3. Dispatch dynamic tool calls with automated routing and observation capture.
  4. Verify multi-server coordination and error recovery across automated pytest tests.

Expected output

============================= test session starts ==============================
collected 5 items

tests/test_mcp_client.py .....                                           [100%]

============================== 5 passed in 0.02s ===============================
[MCP CLIENT] Connected to 'database-server' (1 tool: 'sql_select')
[MCP CLIENT] Connected to 'filesystem-server' (1 tool: 'read_file')
[ROUTING] Dispatched 'sql_select' -> Server 'database-server'
[ROUTING] Dispatched 'read_file' -> Server 'filesystem-server'
[EXECUTION SUCCESS] Both multi-server actions executed successfully.

Validate your work

Run the pytest test suite:

pytest tests/run_tests.sh

Troubleshooting

  1. Subprocess hangs on readline: Ensure the server flushes its standard output after writing each line.
  2. Tool routing KeyError: Verify the tool name exists in self.tool_routing.

Common mistakes

Practice assignment

Add Tool Namespacing support to the client, automatically prefixing tool names with the server name (e.g. sqlite__query vs postgres__query) to resolve naming collisions.

Extension challenge

Implement an asynchronous AsyncMCPClientPool utilizing asyncio.subprocess that executes tool calls across multiple servers concurrently in parallel.

Quiz

Q1. What is the primary role of an MCP Host Client in an autonomous agent system?

  1. To manage servers, discover tools, and route calls
  2. To train transformer model weights
  3. To compile C++ header files
  4. To format Markdown tables in the browser
Show answer

Answer: A. To manage servers, discover tools, and route calls

The client acts as the central orchestrator bridging the language model's reasoning loop with external MCP server subprocesses.

Q2. How does an MCP client determine which server should handle a specific tool call when connected to multiple servers?

  1. It broadcasts the tool call to all servers simultaneously
  2. A routing table from tool name to server
  3. It asks the user to pick a server every time
  4. It hashes the tool name to a random port
Show answer

Answer: B. A routing table from tool name to server

The client builds a unified tool registry during initialization, mapping tool names to server connections for direct routing.

Q3. What should an MCP client do if a child server process terminates abruptly during a tool call?

  1. Crash the entire host application without error logs
  2. Delete the client configuration
  3. Catch the EOF, report it, and respawn
  4. Ignore the error and pretend the tool succeeded
Show answer

Answer: C. Catch the EOF, report it, and respawn

Resilient clients catch process failures and feed structured error observations back into the agent scratchpad.

Q4. How are MCP tools exposed to modern LLM APIs (such as OpenAI or Anthropic SDKs)?

  1. By creating binary DLL plugins
  2. By embedding Python bytecode into the prompt
  3. By converting all tools into bash scripts
  4. By converting tools/list into the provider's format
Show answer

Answer: D. By converting tools/list into the provider's format

MCP tool schemas map 1:1 into standard JSON Schema function declarations accepted by foundation model APIs.

Q5. What is the recommended cleanup procedure when an MCP client shuts down?

  1. Signal the subprocesses and close the pipes
  2. Leave all subprocesses running indefinitely
  3. Delete the operating system temp directory
  4. Reboot the machine
Show answer

Answer: A. Signal the subprocesses and close the pipes

Proper lifecycle management requires terminating child subprocesses to prevent orphan processes from consuming system resources.

Glossary

MCP Host Client
The controlling application that connects to MCP servers, manages tool discovery, and interfaces with the LLM.
Multi-Server Pool
An array of active MCP server connections managed concurrently by a single host client.
Tool Routing Table
An in-memory dictionary mapping tool names to their corresponding server connection instances.
Schema Ingestion
Fetching `tools/list` from connected servers and translating definitions into model-compatible tool parameters.
Subprocess Lifecycle
The automated management of spawning, monitoring, communicating with, and killing server subprocesses.
Dynamic Tool Dispatch
Parsing an LLM tool call decision and dispatching the JSON-RPC request to the responsible server.
Broken Pipe Recovery
Handling unexpected server termination cleanly without crashing the primary agent loop.
Unified Scratchpad
The cumulative conversation history recording tool calls across multiple distinct MCP backends.

Sources and further reading


Kept in this browser, no account needed. Your progress page turns the whole record into one link you can bookmark or open on another device.