Build Your Own MCP Server: An Open-Source Lab From Real SaaS Work
MCPClaudeTeachingOpen Source
github.com → (opens in new tab)What It Is
A free, hands-on lab that teaches developers to connect their own product to Claude and other AI tools with the Model Context Protocol (MCP). You build one server step by step, from a first tool to remote sign-in with OAuth, for a made-up plant shop's social media scheduler. Every lesson comes from a problem I first hit while building Postapop's own MCP server for Claude.
What Learners Build
- Core lab, steps 1 to 6 (45 minutes). A server with mock data, a read tool, a write tool with validation, tool descriptions that models read well, a connection to Claude, and the same server over HTTP.
- Remote sign-in, step 7 (40 minutes). OAuth 2.1 the way Claude and ChatGPT expect it: discovery documents, client ID metadata documents, PKCE, a consent page and rotating refresh keys.
- Advanced steps 9 to 11 (about 35 minutes each). Pictures by reference from another service, pictures as files from the chat, and letting the model use the person's own material safely: text that other people wrote, private links and long texts.
Built to Be Taught
- Every step is a Git tag with passing tests, from
step-1tostep-11. Learners can start anywhere and compare their code with a working version. The full suite has 268 tests. - Instructor notes with timings and the problems people usually hit, plus notes on how real MCP clients differ from each other.
- Checked every week. One automatic run tests every step, and another warns early when the latest MCP SDK would break the lab.
- No account or API key needed. The lab uses mock data and shares no code with Postapop. MIT licence.
The Design Lessons It Teaches
- The server holds no business logic. Product rules live behind one API, so the app and the AI connection never disagree.
- Errors are sentences. Each expected error says what went wrong and what to do next, so the model can fix its own call.
- Read tools and action tools are separate. Annotations only help the client decide when to ask the user. The API enforces every rule itself.
- Text from users and third parties is labelled and fenced before a model sees it, so words that look like instructions stay inert.
Who It's For
Developers who want to connect their product to AI tools, and the people who teach or demo that work: solutions engineers, developer advocates and trainers. For a guided, in-person version of this kind of building, see my AI workshops.