Estudo MCP server
Commit Nov 6, 2026Provides a collection of functional Python-based MCP servers demonstrating tools, resources, prompts, sampling, and HTTP transport with authentication.
Also known as andreluizpedroso/mcp-servers-python
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 6, 2026
- License
- MIT
What is Estudo MCP?
Estudo provides a collection of functional Python-based MCP servers demonstrating tools, resources, prompts, sampling, and HTTP transport with authentication.
Summary generated from the project's README
About Estudo MCP server
Learning the Model Context Protocol through practical implementation is what this collection of Python-based servers enables. Developers can study how to build functional servers from scratch using the official Python SDK and the uv package manager. The repository provides a series of incremental projects that move from basic tool implementation to advanced features like HTTP transport with Bearer token authentication.
Each project serves as a standalone unit with its own dependencies and test suite. You can run these servers locally using stdio transport or test them via the MCP Inspector. The collection covers a wide range of protocol primitives including Tools, Resources, Prompts, Sampling, and Roots. It is designed for engineers who want to move beyond documentation by interacting with real-world implementations that include automated testing with pytest and end-to-end validation.
What you can do with it
- 1Implement task management toolsA developer can use the sprint 02 server to see how to build a task manager with in-memory state and unit tests.
- 2Build a notes libraryYou can study how to implement static and template-based resources alongside prompts using the sprint 03 server.
- 3Create a Git assistantUse the final project to see a complete implementation of a Git repository assistant using tools, resources, and prompts.
Written from the project's README. Every use case is checked against a quote from it.
README
View on GitHubEstudo-MCP — Model Context Protocol in Practice
A guided, hands-on study of the Model Context Protocol (MCP), built from scratch over 8 incremental sprints. Each sprint delivers a working, tested MCP Server — not just documentation examples — covering the entire protocol: Tools, Resources, Prompts, Sampling, Roots, remote transport and authentication.
Table of Contents
- About the Project
- Sprint Progress
- What Was Built
- Real Bugs Found Along the Way
- Repository Structure
- How to Run
- Methodology
- References
About the Project
The Model Context Protocol is the open standard that lets AI applications (Hosts) connect to external tools and data sources (Servers) in a uniform way — removing the need for a proprietary integration for every application × tool combination.
This repository documents a from-scratch study of MCP that goes beyond reading the specification: each sprint produces a real MCP server, with automated tests and end-to-end validation (via a real ClientSession, MCP Inspector, or both), progressively covering:
Tools → Resources & Prompts → Inspection/debugging → Custom Client → Sampling & Roots → HTTP Transport + Auth → Final project
Sprint Progress
| # | Sprint | Deliverable | Status |
|---|---|---|---|
| 1 | MCP fundamentals + environment setup | uv environment + validated official SDK |
✅ |
| 2 | First MCP Server — Tools | Task manager (servers/sprint-02-tools-server) |
✅ |
| 3 | Resources & Prompts | Notes library (servers/sprint-03-resources-prompts) |
✅ |
| 4 | Testing with MCP Inspector | Visual and --cli validation |
✅ |
| 5 | Custom MCP Client + real Host | Generic client (servers/sprint-05-custom-client) |
✅ |
| 6 | Sampling & Roots | Server implementing both primitives (servers/sprint-06-sampling-roots) |
✅ |
| 7 | HTTP Transport + Authentication | streamable-http server with Bearer token (servers/sprint-07-http-auth) |
✅ |
| 8 | Final project | Git repository assistant (servers/sprint-08-final-project) |
✅ |
Each sprint in docs/sprints/ follows a fixed format: objective, concepts taught, architectural decisions, validation questions, code review (with a grade) and interview questions — see Methodology.
What Was Built
| Server | MCP primitives | Highlight |
|---|---|---|
sprint-02-tools-server |
Tools | 4 Tools with in-memory state, unit tests + smoke test via a real Client |
sprint-03-resources-prompts |
Resources (static + template) and Prompts | Two Prompt return forms (str and list[Message]) |
sprint-05-custom-client |
Generic Client | Works against any stdio server; 4 actions (list/call/read/prompt) |
sprint-06-sampling-roots |
Sampling and Roots | Server → Client → Server round trip validated with stub callbacks |
sprint-07-http-auth |
HTTP Transport + Auth | Custom TokenVerifier, tested with missing/invalid/valid tokens |
sprint-08-final-project |
Tools + Resources + Prompts | Git repository assistant, tested against this repo's real history |
All servers are built with the official Python SDK (FastMCP) and have their own test suite (uv run pytest).
Real Bugs Found Along the Way
Building the exercises against real Clients (rather than only reading the documentation) surfaced concrete problems, which were fixed during development:
| Sprint | Bug | Cause | Fix |
|---|---|---|---|
| 5 | Traceback when propagating a Tool error | SystemExit raised inside async with breaks the anyio.TaskGroup cleanup |
Return the exit code and call SystemExit only outside the async scope |
| 7 | Silent DeprecationWarning |
HTTP client API was renamed (streamablehttp_client → streamable_http_client) |
Migrated to the current API, with an explicit httpx.AsyncClient |
| 7 | Orphan process holding the port | uv run on Windows spawns a child process that survives Popen.terminate() |
taskkill /PID <pid> /T /F (kills the whole process tree) |
| 8 | git log/git show hanging indefinitely |
The git subprocess inherited the server's stdin, which under stdio is the MCP protocol pipe |
Explicit stdin=subprocess.DEVNULL on every subprocess.run |
| 8 | Resource template not matching nested paths | The SDK generates [^/]+ for each {param} — it does not accept / |
Slashes encoded as %2F in the URI, decoded in the Server |
Repository Structure
MCP/
├── README.md
├── docs/
│ └── sprints/ # 1 document per sprint
│ ├── sprint-01.md … sprint-08.md
└── servers/ # 1 independent uv project per sprint
├── sprint-01-hello-mcp/
├── sprint-02-tools-server/
├── sprint-03-resources-prompts/
├── sprint-05-custom-client/
├── sprint-06-sampling-roots/
├── sprint-07-http-auth/
└── sprint-08-final-project/
Each folder in servers/ is a self-contained uv project with its own pyproject.toml, uv.lock and virtual environment — no dependencies are shared between sprints.
How to Run
Prerequisite: uv installed (it resolves the Python version automatically).
# Enter a specific sprint's project
cd servers/sprint-02-tools-server
# Install dependencies
uv sync
# Run the tests
uv run pytest -v
# Start the server (stdio transport, or streamable-http in Sprint 7)
uv run server.py
To explore a server interactively without writing Client code, use the MCP Inspector (see Sprint 4):
npx @modelcontextprotocol/inspector uv run server.py
Methodology
Each sprint in docs/sprints/ follows the same structure:
- Objective — what the sprint delivers
- Concepts taught — what needs to be understood before the exercise
- Architectural decisions — design choices, with discarded alternatives and the reasoning
- Validation questions — check conceptual understanding, answered in my own words
- Code review — grade and concrete feedback on the code produced in the sprint
- Interview questions — technical-interview-style questions, with a grade and identified gaps
References
Estudo MCP questions
What MCP primitives are implemented in these servers?
The servers cover the entire protocol including Tools, Resources, Prompts, Sampling, Roots, and HTTP transport.
Does the project support authentication?
Yes, one of the implementations includes a streamable-HTTP server that uses Bearer token authentication.