Module 8: Project — Real-World MCP Server
Final Project: Real MCP Server (Production-Ready)
Final Project: Real MCP Server (Production-Ready)
Capsule description
This is the moment. Seven modules of preparation brought you here. You learned what MCP is and why it matters. You understood the Host-Client-Server architecture. You mastered the three primitives — Resources, Tools, Prompts. You built MCP servers in TypeScript and Python. You created MCP Apps with interactive UI. You learned to test, debug, and configure servers in Claude Code.
Now you're going to use all of that to build something real.
Not an exercise. Not a guided tutorial. A production-ready MCP server that connects Claude Code with a real database or API — something you'll keep using after completing this guide.
Why an integrative project
The mini-projects from the previous modules gave you pieces: a minimal server with 3 primitives (module 3), a TypeScript server with tools and resources (module 4), a Python server connected to the GitHub API (module 5), an MCP App with a dashboard (module 6), a test suite (module 7). Each piece solved an isolated aspect.
This project is where the pieces come together. You design the architecture from scratch. You implement all the primitives for a coherent use case. You write tests that verify everything works together. You document the server so anyone can use it. And you connect it to Claude Code to demonstrate that it works end-to-end.
The difference between "I know how to build an MCP server" and "I can deliver an MCP server" is exactly this project.
Where are we?
Context in the guide
Phase 1: MCP Fundamentals (Modules 1-3)
✅ Module 1: What MCP is and why it matters
✅ Module 2: Host-Client-Server Architecture
✅ Module 3: Three Primitives — Resources, Tools, Prompts
Phase 2: Build MCP Servers (Modules 4-6)
✅ Module 4: MCP Server in TypeScript
✅ Module 5: MCP Server in Python
✅ Module 6: MCP Apps and Interactive UI
Phase 3: Production (Modules 7-8)
✅ Module 7: Testing, Debugging, and Integration
→ Module 8: Project — Real MCP Server (YOU ARE HERE)
Everything you bring
Take an inventory of what you already know. This isn't rhetoric — each of these skills appears in the project:
| Skill | Module where you learned it | How you'll use it |
|---|---|---|
| Host-Client-Server architecture | Module 2 | Design the communication between Claude Code and your server |
| Resources (contextual data) | Module 3 | Expose data from your database/API so Claude Code can read it |
| Tools (executable functions) | Module 3 | Create CRUD operations that Claude Code can invoke |
| Prompts (reusable templates) | Module 3 | Define standardized workflows for common interactions |
| TypeScript or Python SDK | Modules 4-5 | Implement the server in the language you prefer |
| Validation with Zod/Pydantic | Modules 4-5 | Validate all tool inputs |
| Async patterns | Module 5 | Handle I/O with the database/API |
| Error handling | Modules 4-5, 7 | Handle failures gracefully |
| Testing (unit + integration) | Module 7 | Write a complete test suite |
| Debugging with MCP Inspector | Module 7 | Verify that everything works before connecting to Claude Code |
| Configuration in Claude Code | Module 7 | Connect your server and use it end-to-end |
You're ready.
What you're going to build
The concept
A complete MCP server that connects Claude Code with a real data source. When you finish, you'll be able to open Claude Code and do things like:
- "Show me all the active users in the database"
- "Create a new project with this data"
- "Generate a report of the tasks completed this week"
- "Analyze the structure of the
orderstable and suggest indexes"
Claude Code will use your MCP server to execute these operations. Not a generic server, not a tutorial example — something you designed, implemented, and tested.
Project requirements
Your MCP server must include:
| Component | Minimum | Recommended |
|---|---|---|
| Resources | 3 | 5-8 |
| Tools | 5 | 8-12 |
| Prompts | 2 | 3-5 |
| Test suite | Unit tests for each tool | Unit + integration tests |
| Documentation | README with setup | README + API reference |
| Error handling | Try/catch in each operation | Logging + descriptive errors |
Deliverables
At the end of module 8, you deliver:
- Source code of the complete MCP server
- Test suite that passes with
pytest(orvitest) - README.md with setup, usage, and API reference instructions
- Demo of Claude Code using your server in at least 5 real scenarios
- Reflection on design decisions and trade-offs
The 3 project options
You have three paths. Choose the one that best aligns with your stack, your interests, or your current work.
Option A: SQLite + Python MCP Server
For whom: Students on the Backend Python path, or anyone who wants to work with a local database.
Stack:
- Python 3.11+
- MCP Python SDK (
mcp[cli]) - SQLite (included in Python)
- Pydantic for validation
- pytest for testing
What you build: An MCP server that exposes a complete SQLite database to Claude Code. Claude Code can query tables, create records, run queries, and get reports — all through your server.
Domain example: Task management system, product inventory, course catalog, expense log.
Why choose this option:
- You don't need to install anything extra (SQLite comes with Python)
- Local database = zero network latency
- Ideal if you come from the Backend Python Bootcamp
- Total control over the data
- Easier to test (in-memory database for tests)
Concrete example of what Claude Code could do with your server:
You: "How many tasks were completed this week?"
Claude Code: [uses tool query_records] → "14 tasks were completed this week.
The most recent ones: 'Migrate database to v2', 'Update dependencies',
'Write integration tests'..."
Complexity: ⭐⭐⭐ (medium)
Option B: File System + TypeScript MCP Server
For whom: Students who prefer TypeScript, or who want a server that interacts with local files.
Stack:
- Node.js 18+
- MCP TypeScript SDK (
@modelcontextprotocol/sdk) - File system (fs/promises)
- Zod for validation
- Vitest for testing
What you build: An MCP server that exposes file system operations to Claude Code. Claude Code can list directories, read files, search content, analyze project structures, and generate reports about codebases.
Domain example: Project explorer, codebase analyzer, documentation manager, file organizer.
Why choose this option:
- TypeScript is the main language of the MCP ecosystem
- File system = local data, no database setup
- Useful as a real tool for your development workflow
- Zod schemas give you strong typing end-to-end
Concrete example of what Claude Code could do with your server:
You: "Analyze the structure of my project in /Users/me/my-app"
Claude Code: [uses tool analyze_project_structure] → "Your project has 47 files
in 12 directories. Main stack: TypeScript (68%), CSS (22%), HTML (10%).
Structure: monorepo with src/, tests/, docs/. 3 unused files detected..."
Complexity: ⭐⭐⭐ (medium)
Option C: External API + MCP Server (any language)
For whom: Students who want to integrate an existing service they already use.
Stack:
- Python or TypeScript (your choice)
- Corresponding MCP SDK
- External REST API (GitHub, Notion, Jira, Todoist, Weather, etc.)
- httpx (Python) or fetch (TypeScript) for HTTP
- Corresponding testing framework
What you build: An MCP server that connects Claude Code with a real external API. Similar to the module 5 project (GitHub Explorer) but more complete: more tools, more resources, prompts, tests, documentation.
Domain example: Project management (Jira/Todoist), documentation (Notion), CI/CD (GitHub Actions), monitoring, CRM.
Why choose this option:
- You integrate something you already use in your work
- Immediate practical value
- Experience with authentication and real APIs
- The server is immediately useful after the guide
Concrete example of what Claude Code could do with your server:
You: "What issues does the frontend team have assigned this week?"
Claude Code: [uses tool list_issues with a filter] → "The frontend team has
8 open issues: 3 bugs (P1), 2 features (P2), 3 improvements (P3).
The most urgent issue is 'Fix login redirect loop' assigned to @mary..."
Complexity: ⭐⭐⭐⭐ (medium-high, because of the external API dependency)
Which one to choose?
| If... | Choose |
|---|---|
| You come from the Backend Python Bootcamp | Option A |
| You prefer TypeScript and want something useful for coding | Option B |
| You want to integrate a service you already use daily | Option C |
| You don't know which one to choose | Option A (the guide uses this as the main example) |
This guide uses Option A (SQLite + Python) as the main example. All the code in capsules 2-4 follows this option. If you choose B or C, adapt the patterns — the architecture is the same, only the data source changes.
Timeline and milestones
Project structure by capsule
| Capsule | What you do | Estimated duration |
|---|---|---|
| 02 - Design and Architecture | You decide which resources, tools, and prompts to expose. You design schemas. You plan the project structure. | 30-45 min |
| 03 - Core Implementation | You implement the complete server: database, resources, tools, prompts, error handling. | 60-90 min |
| 04 - Testing and Documentation | You write a complete test suite and documentation. | 45-60 min |
| 05 - End-to-End Demo | You connect to Claude Code, do the demo, final checklist. | 30-45 min |
Estimated total: 2.5 - 4 hours
Verification milestones
After each capsule, you should be able to verify that you're on the right track:
- After Capsule 02: You have a design document with all the planned resources, tools, and prompts. The file structure exists (empty).
- After Capsule 03: The server runs and responds in MCP Inspector. All the tools and resources work manually.
- After Capsule 04:
pytest(orvitest) passes with all the tests. The README is written. - After Capsule 05: Claude Code uses your server in real flows. The demo shows at least 5 scenarios.
Evaluation rubric (100 points)
1. Resources (15 points)
| Criterion | Points | Description |
|---|---|---|
| Sufficient quantity | 5 | At least 3 resources implemented |
| Well-designed URIs | 3 | Descriptive URIs that follow conventions (e.g., db://tables, db://table/{name}/schema) |
| Real data | 4 | The resources return real data, not hardcoded |
| Error handling | 3 | They handle errors gracefully (table doesn't exist, connection lost) |
2. Tools (25 points)
| Criterion | Points | Description |
|---|---|---|
| Sufficient quantity | 5 | At least 5 tools implemented |
| Complete CRUD | 5 | At least create, read, update, delete for one entity |
| Input validation | 5 | All the tools validate inputs with Pydantic/Zod |
| Clear descriptions | 3 | Each tool has a description that Claude Code can understand |
| Error handling | 4 | Descriptive errors for each case (not found, validation, connection) |
| Advanced operations | 3 | At least 1 tool that does something more than basic CRUD (query, report, analysis) |
3. Prompts (10 points)
| Criterion | Points | Description |
|---|---|---|
| Sufficient quantity | 3 | At least 2 prompts implemented |
| Useful and reusable | 4 | The prompts solve real recurring interactions |
| Well-defined parameters | 3 | The prompts accept parameters that make them flexible |
4. Testing (20 points)
| Criterion | Points | Description |
|---|---|---|
| Unit tests per tool | 8 | Each tool has at least 1 happy path test and 1 error test |
| Resource tests | 4 | Resources tested with known data |
| Integration tests | 5 | At least 2 tests that verify complete flows (create → read → update → delete) |
| Tests pass | 3 | pytest or vitest runs without errors |
5. Documentation (15 points)
| Criterion | Points | Description |
|---|---|---|
| README with setup | 5 | Clear instructions to install and configure the server |
| API reference | 5 | List of all the tools, resources, and prompts with description and parameters |
| Claude Code instructions | 3 | How to connect the server to Claude Code |
| Usage examples | 2 | At least 3 examples of how to use the server |
6. End-to-End Demo (10 points)
| Criterion | Points | Description |
|---|---|---|
| Server connected to Claude Code | 3 | The server appears in /mcp with "connected" status |
| Real flows demonstrated | 5 | At least 5 scenarios where Claude Code uses the server naturally |
| No errors in the demo | 2 | The demo works without crashes or errors |
7. Code quality (5 points)
| Criterion | Points | Description |
|---|---|---|
| Type hints / typing | 2 | All the code uses type hints (Python) or TypeScript strict mode |
| Clean project structure | 2 | Organized files, separation of concerns |
| No dead code | 1 | No unused functions, unnecessary imports, or commented-out code |
Grading scale
| Range | Level |
|---|---|
| 90-100 | Exceptional — production-ready server, ready to share |
| 80-89 | Excellent — complete server with good practices |
| 70-79 | Good — functional server with areas for improvement |
| 60-69 | Acceptable — meets the minimum requirements |
| < 60 | Incomplete — needs additional work |
Tips for a successful project
Before diving into design and implementation, some tips based on common mistakes:
Choose a domain you know
If you work with project management, build a project management server. If you handle inventory, build an inventory server. If you're a student and organize your tasks in your own system, build a server for that.
A domain you know lets you focus on the MCP implementation instead of wasting time understanding the business rules. You'll instinctively know which tools you need, what data to expose as resources, and which queries are the most common (candidates for prompts).
Start small, expand later
The temptation is to design 15 tools from the start. Resist it. Start with the minimum 5. Make them work end-to-end. Add more later if you have time to spare.
A server with 5 well-tested and documented tools is worth more than one with 15 half-working tools.
Don't ignore the prompts
Prompts are the most underrated primitive. A good prompt transforms 3-step interactions into 1-step interactions. "Use the weekly_report prompt for the week of March 10" is much more powerful than explaining to Claude Code step by step what data to query and how to format the report.
Test while you implement, not at the end
For each tool you implement, write its test immediately. Don't leave all the tests for capsule 04. If something fails, it's easier to detect the problem when you've just written the code.
What this project is NOT
To avoid misunderstandings:
- It's not a guided tutorial. Capsules 2-4 show a complete example (Option A), but you design and implement your own server. Use the example as a reference, not as a template to copy.
- It doesn't need deployment to production. "Production-ready" means robust code with tests and documentation, not that it's running on a cloud server.
- It doesn't need to be huge. A well-designed server with 5 tools, 3 resources, and 2 prompts is better than one with 20 tools without tests or error handling.
- It's not an exam. The rubric is a guide to make sure your server is complete. If something doesn't apply to your use case, document why.
Before you start: preparation checklist
Before advancing to capsule 02 (design), verify that you have everything ready:
- Option chosen: You know whether you're going with A (SQLite + Python), B (File system + TypeScript), or C (external API)
- Domain defined: You have an idea of what data/operations your server will handle (tasks, products, files, API)
- Environment configured: Python 3.11+ or Node.js 18+ installed, MCP SDK installed
- MCP Inspector functional: You can run
mcp devand see the debugging interface - Claude Code configured: You can run
claudeand connect MCP servers withclaude mcp add - Module 7 completed: You know how to write tests for MCP servers and diagnose connection problems
If anything on this list fails, go back to the corresponding module before continuing. This project assumes that everything before it works.
The complete arc of the project
Think of it this way: in the next 4 capsules you're going to go through the same process a professional developer follows when building a real integration:
- Design before code — You decide what to expose, how to organize the data, and which problems to solve. You plan before writing the first line.
- Incremental implementation — You build the server piece by piece: first the database, then resources, tools, prompts. Each step is verifiable.
- Testing as a safety net — You write tests that let you refactor with confidence. If something breaks, you know immediately.
- Demo as validation — You connect everything to Claude Code and demonstrate that it works in the real world, not just in isolated tests.
This process isn't ceremonial. It's how reliable tools are built. And at the end of this module, you'll have built one.
Module structure
Capsule 01: Project introduction (YOU ARE HERE)
→ Scope, options, requirements, rubric, timeline
Capsule 02: Design and Architecture
→ Which resources, tools, prompts to expose
→ Schema design, file structure
→ Complete example for each option
Capsule 03: Core Implementation
→ Complete implementation of Option A (SQLite + Python)
→ Database setup, resources, tools, prompts, error handling
→ Complete and executable code
Capsule 04: Testing and Documentation
→ Complete test suite with pytest
→ README template
→ API documentation
Capsule 05: End-to-End Demo
→ Configure in Claude Code
→ 5 real usage scenarios
→ Final checklist, retrospective, what comes next
Each capsule depends on the previous one. Don't skip.
Summary
- This module is the integrative project of the entire guide — 5 capsules building a real MCP server
- It integrates the 7 previous modules: protocol, architecture, primitives, SDKs, testing, and debugging
- The server uses SQLite as the database and exposes complete Resources, Tools, and Prompts
- It's evaluated with a 100-point rubric that covers code, testing, documentation, and functionality
- The project goes through 4 phases: design → implementation → testing/docs → end-to-end demo
- When you finish, you'll have a production-ready MCP server that works in Claude Code
Resources
- MCP Python SDK — Official SDK for Python
- MCP TypeScript SDK — Official SDK for TypeScript
- SQLite Documentation — SQLite reference
- Pydantic v2 Documentation — Validation and serialization in Python
- MCP Inspector — Visual debugging tool
- Claude Code MCP Configuration — Official documentation of MCP in Claude Code