Overview
Who it is for: anyone who knows a little Python and wants to understand, rebuild or extend a real MCP server with search, sign-in and permissions, from beginners to working engineers. Each module says what to read first.
What you will learn
- 22 written parts, yours for good
- 8h 7m of reading, measured not estimated
- Written for the intermediate level
- Every future revision included
Curriculum
22 sections · 22 parts · 8h 7m47 min free to read · 7h 20m with the project
01Start here1 part · 3 min
02Module 0: Project overview: a guided tour of Wayfinder1 part · 21 min
03Module 1: The problem: knowledge AI assistants cannot see1 part · 23 min
04Module 2: The solution: an MCP server with permission-aware retrieval1 part · 21 min
- Module 2: The solution: an MCP server with permission-aware retrieval21 min
05Module 3: MCP in depth: protocol, transports and the SDK1 part · 22 min
- Module 3: MCP in depth: protocol, transports and the SDK22 min
06Module 4: High-level design1 part · 20 min
- Module 4: High-level design20 min
07Module 5: Low-level design: data, ids, API and schemas1 part · 23 min
- Module 5: Low-level design: data, ids, API and schemas23 min
08Module 6: The seed company: Tidewater Freight1 part · 23 min
- Module 6: The seed company: Tidewater Freight23 min
09Module 7: The access model: groups and visibility1 part · 20 min
- Module 7: The access model: groups and visibility20 min
10Module 8: Indexing and embeddings1 part · 25 min
- Module 8: Indexing and embeddings25 min
11Module 9: Hybrid search and ranking1 part · 25 min
- Module 9: Hybrid search and ranking25 min
12Module 10: Permission filtering before ranking1 part · 24 min
- Module 10: Permission filtering before ranking24 min
13Module 11: The MCP tools, resources and prompts1 part · 25 min
- Module 11: The MCP tools, resources and prompts25 min
14Module 12: OAuth 2.1 for MCP clients and personal tokens1 part · 22 min
- Module 12: OAuth 2.1 for MCP clients and personal tokens22 min
15Module 13: Writing safely: create_issue and elicitation1 part · 23 min
- Module 13: Writing safely: create_issue and elicitation23 min
16Module 14: The audit log and redaction1 part · 25 min
- Module 14: The audit log and redaction25 min
17Module 15: The web console1 part · 25 min
- Module 15: The web console25 min
18Module 16: Connecting Claude Code, Cursor and Claude Desktop1 part · 21 min
- Module 16: Connecting Claude Code, Cursor and Claude Desktop21 min
19Module 17: Evaluating retrieval and the 0-leak gate1 part · 24 min
- Module 17: Evaluating retrieval and the 0-leak gate24 min
20Module 18: Security: threats and fixes1 part · 24 min
- Module 18: Security: threats and fixes24 min
21Module 19: Containers and the local stack1 part · 23 min
- Module 19: Containers and the local stack23 min
22Module 20: Deploying to Google Cloud with CI/CD1 part · 25 min
- Module 20: Deploying to Google Cloud with CI/CD25 min
A working engineering knowledge hub, Wayfinder, taken apart in illustrated modules. Engineers connect the AI assistant they already use (Claude Code, Cursor or Claude Desktop) through the Model Context Protocol and ask "Why does billing retry three times?", "Who owns routing?" or "What did we decide about Kafka?". Wayfinder searches the team's docs, runbooks, postmortems, architecture decisions, issues and pull requests, and returns cited passages that this engineer is allowed to read: the permission filter runs inside the database query, before anything is ranked. The server has no language model of its own; the assistant's model writes the answer from the passages. One write tool files an issue only after the user confirms it, every call lands in an audit log, and a React console lets people search as themselves, connect their client and see who can read what. The demo company, Tidewater Freight, is fictional: 41 people, 6 teams and 403 sources.
Who it is for: anyone who knows a little Python and wants to understand, rebuild or extend a real MCP server with search, sign-in and permissions, from beginners to working engineers. Each module says what to read first.
How each module is laid out
| Section | Answers |
|---|---|
| Where this fits | the same system map in every module, with this module's parts highlighted |
| What it does | the idea in one picture, then each production practice at a glance: what, why, how, when, where |
| Use cases and examples | the same practice at Tidewater Freight and in other industries |
| How it works | the mechanism step by step, one figure per step, with real values |
| Code tour | the real files, short excerpts, every line explained, concept boxes for new ideas, and a "what happens when" trace |
| Design decisions | what was chosen, the alternatives and why, with measured numbers, and when to choose differently |
| What can go wrong | failures and attacks, how the code handles each, and the test that proves it |
| Try it yourself | exact commands and what you should see |
| Check yourself, Key terms | a short quiz and a glossary |
Source code
The complete, runnable project as one zip: the code the modules explain, with its tests and the files to run and deploy it.
The source code download comes with buying this project.
Submit your build
When the last milestone runs, hand in the repository and three lines about it. That is what the project page will show for you, and what you can send with a job application.
Sign in to submit your build: the repository link and three lines about it.
Reviews
to review this project once you have finished it.