mcpstepbystep

the staircase

Tutorials

MCP, step by step: work through the staircase in order or jump to your level. Every tutorial is evergreen, version-pinned, has runnable code, and ends with the next step.

Foundations

Zero to a working MCP server, connected to every client you use.

  1. 01 What is MCP? How the Model Context Protocol actually works The Model Context Protocol explained: the N×M problem, hosts, clients and servers, tools, resources and prompts, transports, and how a session starts. ⏱ 15–20 min
  2. 02 How to build an MCP server in Python, step by step Build an MCP server in Python with uv and FastMCP — two tools, a resource and a prompt — test it in the MCP Inspector, then connect Claude Desktop and Claude Code. ⏱ 30–45 min
  3. 03 How to build an MCP server in TypeScript, step by step Build an MCP server in TypeScript with the official SDK — McpServer, zod schemas, stdio transport, a clean build setup, and the stdout logging trap to avoid. ⏱ 30–45 min
  4. 04 How to connect an MCP server to Claude, Cursor, VS Code, and ChatGPT (every config file) Copy-paste MCP configs for Claude Desktop, Claude Code, Cursor, VS Code, ChatGPT, Windsurf and Gemini CLI — config paths, transports, env vars, Windows fixes. ⏱ 20–30 min

Builder

Debugging, primitives, real APIs, remote deployment — servers that do real work.

  1. 05 How to debug an MCP server: Inspector, logs, and a workflow that finds the fault A repeatable workflow for debugging MCP servers: isolate with Inspector, read client logs, and climb the failure ladder from spawn errors to tool bugs. ⏱ 25–35 min
  2. 06 MCP tools vs resources vs prompts: when to use each (with code) Tools, resources, and prompts explained with Python and TypeScript code: who controls each, structured output, annotations, and token-efficient design. ⏱ 25–35 min
  3. 07 How to wrap a REST API in an MCP server (the right way) Wrap a REST API in an MCP server with Python FastMCP and httpx: task-shaped tools, env-var auth, pagination, response trimming, and errors models can fix. ⏱ 40–50 min
  4. 08 How to deploy a remote MCP server with Streamable HTTP Move your MCP server off stdio to Streamable HTTP and deploy it to Cloudflare Workers, Fly.io or a VPS — so your team, Claude and ChatGPT can connect. ⏱ 45–60 min
  5. 09 How to add OAuth to an MCP server, step by step Add OAuth 2.1 to a remote MCP server without hand-rolling it: the resource-server model, RFC 8707 audience checks, DCR vs CIMD, and a middleware sketch. ⏱ 50–60 min

Production

Auth, security hardening, and governance for MCP in production.

  1. 10 MCP security hardening: a practical checklist for real deployments A defensive MCP security checklist: tool poisoning, confused deputy, token passthrough, session hijacking, SSRF and supply chain — mitigations for each. ⏱ 35–45 min

newsletter

One practical MCP guide in your inbox. No news, no hype.

Tutorials and decision frameworks as they ship. Unsubscribe anytime.