What Makes MCP Server Lessons Different from Standard Code Lessons

MCP server lessons teach architectural, production-grade service design using the Model Context Protocol, while standard code lessons focus on isolated, algorithmic implementations within a single runtime.

In the rohitg00/ai-engineering-from-scratch curriculum, MCP server lessons represent a fundamental shift from writing self-contained algorithms to deploying network-accessible services. These lessons appear in Phase 19 as capstone projects, requiring learners to master transport protocols, authentication flows, and multi-server governance rather than simply implementing functions in a single language runtime.

Architectural Scope vs. Algorithmic Focus

Standard code lessons typically present a self-contained program—such as a Python main.py implementing a neural-network layer—that runs and verifies through unit tests inside a single language runtime.

MCP server lessons, documented in phases/19-capstone-projects/13-mcp-server-with-registry/docs/en.md, teach how to expose tools, resources, and prompts through a network service that external agents call via the Model Context Protocol (MCP). This architectural approach requires understanding client-server relationships, serialization, and protocol compliance rather than just algorithm correctness.

Production-Grade Infrastructure Requirements

MCP lessons emphasize transport, authentication, governance, and discovery concerns that standard lessons ignore. These production requirements distinguish MCP-server lessons as full-stack engineering exercises.

StreamableHTTP Transport and Stateless Scaling

While standard lessons often use simple stdio or direct function calls, MCP lessons implement StreamableHTTP transport. As noted in site/data.js under "Step 3: streamable HTTP transport", this replaces the legacy stdio-SSE shape and enables stateless horizontal scaling—critical for production deployments handling multiple concurrent agent connections.

OAuth 2.1 and Human-in-the-Loop Approval

Security in MCP servers involves OAuth 2.1 scopes enforced per-tool. The lesson documentation specifies that destructive actions require a human-approval gate (see docs/en.md lines 21-23). This contrasts sharply with standard lessons where function execution lacks authorization boundaries.

Registry Discovery and Capability Manifests

MCP servers publish capability manifests at /.well-known/mcp-capabilities that a registry service indexes. This discovery mechanism, detailed in docs/en.md lines 23-25, allows teams to dynamically find and enable servers—a concept absent from standalone code lessons.

OPA Policy Gating and Audit Trails

Production MCP implementations include OPA (Open Policy Agent) policy gating and comprehensive audit trails to ensure safe execution of dangerous tools. The skill artifact at outputs/skill-mcp-server.md (lines 14-18) documents these governance layers, which standard lessons rarely address.

Multi-Server Composition Patterns

Unlike single-process standard lessons, MCP lessons require separating read-only and destructive tools into distinct servers. As implemented in docs/en.md lines 81-84, learners must wire these servers together through a client that merges namespaces. This pattern prevents accidental data loss by isolating write operations behind additional security checks while maintaining read performance through dedicated read-only endpoints.

Lesson Deliverables and Artifacts

Standard lessons deliver a main.* file and unit tests. MCP lessons produce artifact files that document the entire service ecosystem:

• A skill file (outputs/skill-mcp-server.md) documenting the deployed server, its tools, and governance model
• A registry UI specification for service discovery
• A conformance-test report verifying protocol compliance

These deliverables reflect the operational reality of running production MCP services versus simply passing algorithmic unit tests.

Code Scaffold Examples

The repository provides minimal scaffolds that learners expand into production systems.

The Python FastMCP skeleton in phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py demonstrates tool declaration with scope validation:

# phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py

"""MCP server + registry + OPA policy gate scaffold."""
import json
from fastmcp import FastMCP, Tool

app = FastMCP()

@app.tool
def list_s3_objects(bucket: str) -> list[str]:
    """Read‑only tool – requires scope `s3:list`."""
    # … implementation omitted …

    return ["obj1.txt", "obj2.txt"]

app.run(host="0.0.0.0", port=8000)   # StreamableHTTP endpoint

For lower-level implementations, the TypeScript scaffold in phases/19-capstone-projects/13-mcp-server-with-registry/code/ts/src/index.ts shows hand-rolled JSON-RPC handling:

// phases/19-capstone-projects/13-mcp-server-with-registry/code/ts/src/index.ts
// Internal MCP server: TypeScript skeleton, hand‑rolled stdio JSON‑RPC.
process.stdout.write("PHASE 19 LESSON 13 - internal MCP server (TypeScript, no SDK)\n");

Both examples serve as foundations for building a full catalog of ten read-only tools plus separate destructive-tool servers with authentication and policy enforcement.

Curriculum Placement and Prerequisites

MCP lessons occupy the capstone phase (Phase 19) of the curriculum, depending on earlier lessons about tools, resources, and agent SDKs. This positioning reflects their complexity: they require synthesis of networking, security, and protocol knowledge. Standard lessons may stand alone or belong to earlier phases focusing on pure math or model fundamentals without external dependencies.

Summary

• MCP server lessons teach network service architecture using the Model Context Protocol, while standard lessons focus on isolated algorithms
• Production concerns like StreamableHTTP transport, OAuth 2.1 authentication, and OPA policy gating are core to MCP lessons but absent from standard code exercises
• MCP lessons require multi-server composition patterns, separating read-only and destructive tools into distinct services
• Deliverables include skill artifacts and registry specifications rather than simple executable scripts
• These lessons appear in Phase 19 as capstone projects requiring mastery of prerequisite tool and agent concepts

Frequently Asked Questions

Why do MCP server lessons use StreamableHTTP instead of stdio?

Standard lessons often use stdio for simplicity, but MCP lessons implement StreamableHTTP to enable stateless horizontal scaling across multiple server instances. As defined in the curriculum's site/data.js, this transport layer allows production deployments to handle concurrent agent connections without maintaining persistent process state, which is essential for high-availability AI infrastructure.

How does the registry service work in MCP lessons?

The registry service indexes capability manifests published at /.well-known/mcp-capabilities endpoints. According to phases/19-capstone-projects/13-mcp-server-with-registry/docs/en.md (lines 23-25), this allows teams to discover available tools dynamically rather than hardcoding server locations, transforming static code lessons into discoverable service ecosystems.

What is the purpose of separating read-only and destructive tools in MCP lessons?

This multi-server composition pattern, detailed in docs/en.md (lines 81-84), isolates dangerous operations behind additional security gates while optimizing read performance. By deploying destructive tools on separate servers with stricter OAuth 2.1 scope requirements and human-approval workflows, the architecture prevents accidental data loss that could occur in monolithic standard lessons.

What deliverables distinguish MCP lessons from standard coding exercises?

While standard lessons produce a main.py file and unit tests, MCP lessons generate skill documentation (outputs/skill-mcp-server.md), registry UI specifications, and conformance-test reports. These artifacts reflect the operational requirements of running production MCP services, including audit trails and OPA policy documentation, rather than merely proving algorithmic correctness.

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