Skip to lesson
supraj.dev THE ENGINEERING HANDBOOKS
LEARN / BUILD / VERIFY2026 edition · checked 06 Oct

THE CONTRACT BETWEEN REASONING AND ACTION

Expose a capability.
Protect the boundary.
Explain the evidence.

Thirty connected lessons on the modern Model Context Protocol: useful tools, clear contracts, authorization and reliable operations.

Start the handbookExplore the chapters
MCP Servers logo

ONE SYSTEM, FOUR QUESTIONS

A protocol is an interface, not a permission system.

01 · Describe

A host discovers a narrow capability and its input contract. Self-reported metadata remains lower-trust information.

02 · Authorize

The host checks the user’s intent; the server verifies identity, operation and object access.

03 · Execute

A bounded handler performs the permitted operation under a separate runtime boundary.

04 · Explain

The host interprets labelled evidence, reports uncertainty and records the actual outcome.

Open a stage to inspect the mechanism. This is an explanatory diagram; it executes nothing.

30connected chapters
68interview questions
5learning stages
1offline capstone
Practice with a clear boundary.The main path is offline. Optional SDK, HTTP, OAuth and model integrations are labelled as separate, unrun work. Nothing on these pages connects an account or executes a tool.
MCP 2026-07-28

Checked 6 October 2026. This edition teaches the current stateless request model and explicitly distinguishes legacy initialization and session examples.

One system, built in stages

ParcelOps is a fictional incident reader. The book separates host decisions, server enforcement and runtime isolation, with synthetic data throughout.

Build understanding, one mechanism at a time.

Each chapter includes a worked example, a safe exercise, expected observations, troubleshooting and two interview questions.

STAGE 01 · 6 CHAPTERS

Understand the contract

  1. 01Three roles, three different responsibilities
  2. 02Choose a protocol era before copying code
  3. 03Discovery and self-contained requests
  4. 04JSON-RPC: correlation, completion and errors
  5. 05stdio is a transport, not a sandbox
  6. 06A first read-only Python server
STAGE 02 · 6 CHAPTERS

Design useful capabilities

  1. 07Design inputs that constrain the operation
  2. 08Outputs, evidence and tool errors
  3. 09Resources: named context with a boundary
  4. 10Prompts are reusable instructions, not authority
  5. 11Caching and pagination without data leaks
  6. 12Subscriptions and change notifications
STAGE 03 · 6 CHAPTERS

Protect the boundary

  1. 13Streamable HTTP and visible routing metadata
  2. 14Authorization discovery and the OAuth boundary
  3. 15Audience, scopes and downstream credentials
  4. 16Treat tool content as untrusted input
  5. 17Approval must bind to an exact intent
  6. 18Multi round-trip input and elicitation
STAGE 04 · 6 CHAPTERS

Operate the integration

  1. 19Deadlines, cancellation and unknown outcomes
  2. 20Observability that preserves privacy
  3. 21Test contracts before connecting a model
  4. 22MCP and the agent loop
  5. 23Extensions: opt in and verify support
  6. 24Deploying a stateless protocol service
STAGE 05 · 6 CHAPTERS

Build with evidence

  1. 25Governance starts with a capability inventory
  2. 26Threat modeling with forbidden-effect tests
  3. 27Migrate legacy integrations deliberately
  4. 28Capstone: a bounded ParcelOps contract lab
  5. 29Benchmark methods before benchmark claims
  6. 30Write an engineering report with evidence

BEFORE YOU START

Bring curiosity.
Keep the boundary clear.

Bring basic Python, JSON and HTTP familiarity. Read the current official SDK prerequisites before the optional server integration. No model provider or cloud account is needed for the offline capstone.

Keep these distinctions close

  • Protocol version and SDK version are different.
  • Tool descriptions do not grant authority.
  • A complete RPC can still contain a tool error.
  • Cancellation does not reverse committed effects.
  • Fixture checks are not protocol conformance certification.

BUILD WITH EVIDENCE

The ParcelOps contract lab

Standard-library checks for synthetic lookup, request metadata, approval binding and cache separation. No model, network or incident writes.

Download the lab ↓

CONNECT THE MECHANISMS

The scenario interview

Eight cases that ask you to explain the failure, choose a bounded check and defend the limits.

Open the interview →

Sources, evidence and limits

Start with the Official MCP specification. Each chapter links to relevant primary documentation. Examples are original teaching fixtures; expected observations are distinguished from executed evidence.

The benchmark and article chapters supply methods and blank templates. They make no invented measurements, deployment claims or completed-lab claims. Reading progress stays in this browser, separately for each book. Every public visitor starts fresh.

Download the blank benchmark template · Download the evidence record