Building an MCP Server and Client

This guide outlines a practical design pattern to implement, test, and deploy an MCP (Model Context Protocol) server and a matching client using FastMCP. It is framework- and cloud-agnostic with concrete examples where helpful.

You will learn:

• The recommended project layout
• Core dependencies and environment setup
• Server design patterns (tools, transports, serialization)
• Client design patterns (connect, list, call)
• Testing patterns (in-memory unit tests and HTTP integration tests)
• Containerization and deployment options

Recommended Project Structure

• server.py — FastMCP server, tools, and HTTP transport startup
• client.py — Minimal FastMCP client example
• test_mcp_inmemory.py — In‑memory, pytest-based unit tests that import the server directly
• test_mcp_server.py — Simplified integration tests against the deployed HTTP server
• Dockerfile — Container build for Cloud Run
• pyproject.toml — Python project and dependency metadata
• requirements.txt — Pinned runtime dependencies for Docker image

Server Design Pattern

Implement the server as a module that exports a single FastMCP instance and decorates Python functions as MCP tools. Keep business logic pure and testable, and return JSON-serializable results.

Core pattern:

from typing import Any, Dict, List
from fastmcp import FastMCP

mcp = FastMCP("Your MCP Server Name")

@mcp.tool()
def your_tool(arg1: str, limit: int = 10) -> List[Dict[str, Any]]:
    """Describe what this tool does in one sentence."""
    # Validate inputs (FastMCP also validates based on type hints)
    # Query/compute your results
    return [{"ok": True, "arg1": arg1, "limit": limit}]

Transports:

• In-memory: ideal for testing via Client(mcp)
• HTTP (streamable): ideal for remote consumption by HTTP clients
• Other transports: depending on FastMCP support and your needs

HTTP startup:

# server.py
import asyncio, os

if __name__ == "__main__":
    asyncio.run(
        mcp.run_async(
            transport="streamable-http",
            host="0.0.0.0",
            port=os.getenv("PORT", 8080),
        )
    )

Notes:

• Prefer explicit, typed function signatures. FastMCP generates JSON Schema automatically.
• Ensure all return values are JSON-serializable (dict, list, str, int, float, bool, None).
• If you expose HTTP, document the base path (e.g., /mcp/) and any auth requirements.

Client Design Pattern

Use the asynchronous context manager to connect, list tools, and call tools. When testing in-memory, pass the server instance directly; when testing remotely, pass the server URL.

Basic patterns:

from fastmcp import Client

# Remote HTTP client
async def main_remote():
    async with Client("https://your-server.example.com/mcp/") as client:
        await client.ping()
        tools = await client.list_tools()
        result = await client.call_tool("your_tool", {"arg1": "value", "limit": 5})