# Building MCP Servers and Clients from First Principles: A Production-Ready Guide

> Learn to build Model Context Protocol MCP servers and clients from first principles with our comprehensive guide. This resource provides a production-ready implementation for advanced AI engineering.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-07-25

---

**The rohitg00/ai-engineering-from-scratch repository teaches you to build Model Context Protocol (MCP) servers and clients from first principles through a structured curriculum, culminating in a reference implementation featuring stateless StreamableHTTP transport, OAuth 2.1 authorization, and OPA policy gates in [`phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py).**

Building MCP servers and clients from first principles requires mastering both the protocol specification and enterprise-grade security patterns. The **AI Engineering from Scratch** curriculum walks you through the entire AI stack—linear algebra to production agents—with dedicated phases for implementing the Model Context Protocol using real-world architectural patterns.

## What Is the Model Context Protocol (MCP)?

The **Model Context Protocol (MCP)** is the de-facto standard for tool-use in LLM-driven assistants. Starting in 2024, it became the dominant wire format for connecting AI agents to external tools, and by 2026 it serves as the default protocol across Anthropic, OpenAI, Google, and most modern IDEs according to the curriculum metadata in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). MCP enables standardized, secure communication between AI clients and tool servers through JSON-RPC over HTTP.

## Curriculum Structure: Learning MCP Across Three Phases

The repository organizes MCP education into progressive phases, each producing a runnable artifact stored under `phases/<phase-number>-<phase-name>/<lesson-slug>/`.

### Phase 13 – Core Server Primitives

Phase 13 introduces the foundational architecture of MCP servers. You will implement a **stateless StreamableHTTP** transport layer, **scoped OAuth 2.1 authorization**, and an **OPA-based policy gate** as documented in [`phases/19-capstone-projects/13-mcp-server-with-registry/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/13-mcp-server-with-registry/docs/en.md). This phase establishes the security and scalability patterns required for production deployments.

### Phase 14 – Client Integration Patterns

Phase 14 shifts focus to the client side, demonstrating how AI agents discover and invoke MCP servers. You learn to parse capability manifests, negotiate authentication scopes, and handle streaming responses from remote tools.

### Phase 17 – Production Governance

Phase 17 addresses enterprise concerns including registry services, governance frameworks, and comprehensive audit logging. This phase teaches you to operate MCP infrastructure at scale with proper observability and compliance controls.

## Architectural Pillars of Production-Grade MCP Servers

The reference implementation in [`phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py) demonstrates seven critical architectural pillars:

### Stateless StreamableHTTP Transport

The server implements **JSON-RPC over HTTP** with streaming support, enabling horizontal scaling behind load balancers. This **StreamableHTTP** transport ensures that any server instance can handle any request without session affinity, as implemented in the main server loop.

### OAuth 2.1 Scope-Based Authorization

Authentication relies on fine-grained OAuth 2.1 scopes defined in the `Token` dataclass. Tokens carry permissions such as `postgres:query:readonly` for safe operations, while destructive tools require a short-lived `approved:by:human` scope for additional authorization layers.

### OPA Policy Gate

The `policy_decide` function implements a Rego-style decision engine that validates every tool invocation. This gate checks tool existence, scope presence, fresh human approval status, and payload size limits before executing any operation, ensuring defense-in-depth security.

### Capability Manifests

Each server publishes a `.well-known/mcp-capabilities` JSON document through the `MCPServer.capabilities()` method. This manifest lists available tools, required OAuth scopes, and transport details, enabling automatic discovery by clients and registry services.

### Registry Service

The `Registry` class maintains an index of all available MCP servers by polling their capability manifests. This in-memory registry provides search functionality and a UI/API for platform teams to discover and enable tools across the organization.

### Audit Logging with PII Redaction

Every tool invocation generates a structured `AuditEntry` logged in JSONL format. A lightweight `redact` function removes personally identifiable information (PII) from logs before dispatch, ensuring compliance with privacy regulations while maintaining operational visibility.

### Destructive-Tool Isolation

Mutating operations run on separate server instances created via `build_destructive_server()`. These isolated servers enforce stricter OAuth scopes and require the human-approval gate, preventing accidental data modification through the read-only interface.

## Implementing an MCP Server from Scratch

The capstone project (Capstone 13) requires standing up a production-grade MCP server with all architectural pillars. Here is how to build and register servers using the reference implementation:

```python
from main import build_readonly_server, build_destructive_server, Registry

# Build a read-only server exposing safe tools

ro_server = build_readonly_server()

# Build a destructive server for mutating operations

rw_server = build_destructive_server()

# Register both servers in the central registry

registry = Registry()
registry.register(ro_server)
registry.register(rw_server)

```

Invoke a tool via the StreamableHTTP endpoint using standard HTTP clients:

```bash
curl -H "Authorization: Bearer eyJhbGci..." \
     -X POST https://mcp.internal.example.com/ \
     -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"postgres.readonly","arguments":{"sql":"SELECT 1"}}}'

```

The response includes policy diagnostics, audit-log confirmation, and the tool result. Search the registry for available tools programmatically:

```python
matches = registry.search("jira")
for server, tool in matches:
    print(f"{tool} available on {server}")

```

## Summary

- **Building MCP servers and clients from first principles** involves implementing the Model Context Protocol with stateless StreamableHTTP transport, OAuth 2.1 authorization, and OPA policy gates.
- The reference implementation lives in [`phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py), providing production-ready code for the `Token` dataclass, `policy_decide` function, and `Registry` class.
- Security architecture separates read-only and destructive tools through `build_readonly_server()` and `build_destructive_server()`, with the latter requiring human approval scopes.
- The `MCPServer.capabilities()` method publishes tool manifests at `.well-known/mcp-capabilities`, enabling automatic discovery by the `Registry` service.
- Comprehensive audit logging via `AuditEntry` and PII redaction ensures compliance while maintaining operational transparency.

## Frequently Asked Questions

### What is the Model Context Protocol (MCP)?

The Model Context Protocol is a standardized JSON-RPC over HTTP protocol that enables LLM-driven assistants to discover and invoke external tools securely. According to the curriculum's [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), MCP became the de-facto standard for tool-use in 2024 and serves as the default wire format across major AI providers and IDEs by 2026.

### How does the curriculum teach MCP implementation?

The rohitg00/ai-engineering-from-scratch repository teaches MCP through three progressive phases: Phase 13 covers server primitives like StreamableHTTP and OPA policies, Phase 14 focuses on client integration, and Phase 17 addresses production governance. Each phase includes runnable code artifacts stored in dedicated lesson folders under the `phases/` directory.

### What security features does the reference MCP server include?

The reference implementation in [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) implements OAuth 2.1 scope-based authorization via the `Token` dataclass, an OPA policy gate through the `policy_decide` function, destructive-tool isolation using separate server builders, and structured audit logging with the `AuditEntry` class. All destructive operations require the `approved:by:human` scope in addition to standard permissions.

### Where is the MCP server code located in the repository?

The complete reference implementation resides in [`phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py), which contains the `MCPServer` class, `Registry` implementation, and security middleware. Documentation explaining the architecture and build instructions is available in [`phases/19-capstone-projects/13-mcp-server-with-registry/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/13-mcp-server-with-registry/docs/en.md).