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

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.

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. 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. 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 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:

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:

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:

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, 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, 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}