This is the capstone. You will design, plan, build, test, and deploy a complete production MCP server from scratch. Everything from the previous four phases comes together here: protocol primitives, design patterns, error handling, security, testing, and deployment.
Pick one of the project options below, or design your own. The goal is a server you would actually use — something you can add to your Claude Desktop config and rely on daily.
Project Brief
Before writing any code, define your project with a structured brief:
## Project Brief Template
### Server Name
<name>-mcp-server
### Purpose
One sentence: what does this server do?
### Target User
Who uses this server? What AI client will they use?
### Core Capabilities
- Tool 1: <name> — <what it does>
- Tool 2: <name> — <what it does>
- Resource 1: <URI pattern> — <what data it exposes>
- ...
### External Dependencies
- API 1: <name> — <what for>, <auth method>
- Database: <type> — <what it stores>
### Security Requirements
- Authentication: <method>
- Sensitive data: <what needs protection>
- Rate limits: <per user, per tool>
### Success Criteria
1. All tools return structured responses
2. Error handling covers: timeout, auth failure, rate limit, invalid input
3. Tests: unit + integration, >80% coverage
4. Deployable via Docker or npm
5. Documentation: README with setup, usage, and examplesArchitecture Design
Design your architecture by answering these questions:
## Architecture Decisions
### Transport
- [ ] stdio (local, single user)
- [ ] SSE (remote, persistent connection)
- [ ] Streamable HTTP (remote, stateless)
Why: <reasoning>
### Tool Design
How many tools? Which patterns apply?
- Polymorphic: <which entities>
- Workflow: <which multi-step processes>
- Idempotent: <which state-changing operations>
### Resource Design
What context does the AI need?
- Context provisioning: <schema, config, docs>
- Dynamic: <what needs parameters>
- Composed: <what should be pre-aggregated>
### Error Strategy
- Structured errors with codes: <list error codes>
- Graceful degradation: <which partial results>
- Circuit breakers: <which dependencies>
- Timeouts: <per operation>
### Data Flow
Draw the path from AI request to response:
Client -> MCP Server -> [Your Logic] -> External API/DB -> Response
### Security Layers
1. Auth: <mechanism>
2. Input validation: <per tool>
3. Rate limiting: <strategy>
4. Audit logging: <what to log>Implementation Plan
Break the build into phases. Each phase should be independently testable.
## Implementation Phases
### Phase 1: Skeleton (1 hour)
- [ ] Project setup (TypeScript, MCP SDK, test framework)
- [ ] Server initialization with name and version
- [ ] One tool registered (simplest one, hardcoded response)
- [ ] Verify: connects to Claude Desktop, tool appears, returns response
### Phase 2: Core Tools (2 hours)
- [ ] Implement all tool handlers with real logic
- [ ] Add input validation with Zod schemas
- [ ] External API/DB integration
- [ ] Unit tests for each handler
### Phase 3: Resources (1 hour)
- [ ] Context provisioning resource(s)
- [ ] Dynamic resources with templates
- [ ] Resource subscription if needed
### Phase 4: Error Handling & Security (1 hour)
- [ ] Structured error responses for all failure modes
- [ ] Circuit breakers for external dependencies
- [ ] Input sanitization
- [ ] Rate limiting
- [ ] Auth (if HTTP transport)
### Phase 5: Testing & Polish (1 hour)
- [ ] Integration tests with MCP Client SDK
- [ ] Error path tests
- [ ] CI/CD workflow
- [ ] README and documentation
### Phase 6: Deploy (30 min)
- [ ] Dockerfile
- [ ] Health check endpoint
- [ ] Structured logging
- [ ] npm publish or Docker pushBuilding It
As you build, apply the checklist from every module:
## Build Checklist
### Protocol
- [ ] Server initializes with name and version
- [ ] All tools have Zod schemas for input validation
- [ ] All tools return structured JSON responses
- [ ] Resources use proper URI patterns
- [ ] Prompts have typed arguments (if used)
### Design Patterns
- [ ] Tools under 15 total (use polymorphic if needed)
- [ ] Multi-step operations use workflow pattern
- [ ] State-changing tools are idempotent
- [ ] Names describe intent, not implementation
- [ ] Descriptions tell the AI WHEN to use each tool
### Error Handling
- [ ] Every error has: code, message, suggestion
- [ ] Partial results returned where possible
- [ ] Retryable flag on transient errors
- [ ] Circuit breakers on external calls
- [ ] Timeouts on all async operations
### Security
- [ ] No credentials in code
- [ ] Parameterized queries (no SQL injection)
- [ ] Input length limits
- [ ] File path sanitization
- [ ] Rate limiting active
### Operations
- [ ] All logging to stderr (zero stdout pollution)
- [ ] Structured log format (JSON)
- [ ] Health check endpoint
- [ ] Graceful shutdown handler
- [ ] Non-root Docker userTesting & Deployment
Final verification before shipping:
## Pre-Ship Checklist
### Tests
- [ ] All unit tests pass
- [ ] All integration tests pass
- [ ] Error paths tested (timeout, auth, rate limit, invalid input)
- [ ] Smoke test: server starts, connects, tool call succeeds
### Manual Testing
- [ ] Added to Claude Desktop, all tools visible
- [ ] Each tool called successfully in a real conversation
- [ ] Error scenarios tested (bad input, API down)
- [ ] Resource reads work from Claude Desktop
### Deployment
- [ ] Docker build succeeds
- [ ] Docker image runs and responds
- [ ] Health check passes
- [ ] Logs are structured and go to stderr
- [ ] Environment variables documented
### Documentation
- [ ] README: what it does, how to install, how to configure
- [ ] Tool descriptions and example usage
- [ ] Environment variable reference
- [ ] Troubleshooting sectionCapstone Project Options
Choose one of these projects, or design your own:
- GitHub Project Manager — tools for managing issues, PRs, and releases. Resources for repo stats and contributor activity. Challenge: polymorphic tools, GitHub API rate limits, pagination.
- Database Explorer — connect to PostgreSQL/MySQL, expose schema as resources, provide query tools with read-only safety. Challenge: SQL injection prevention, result pagination, schema caching.
- Home Automation Hub — control smart devices (lights, thermostat, locks) via MCP. Resources for device status. Challenge: real-time state, device offline handling, security for physical actions.
- Knowledge Base Server — index markdown/docs, provide semantic search and retrieval. Resources for document metadata. Challenge: embedding generation, search relevance, large document handling.
- DevOps Dashboard — server health, deployment status, log analysis, and incident management tools. Challenge: multiple external APIs, circuit breakers, real-time data.
Final Assessment
After completing your capstone, evaluate your server against these criteria:
- Does the AI use your tools correctly on the first try? If not, your naming or descriptions need work.
- What happens when an external dependency fails? Crash? Graceful error? Partial results? The answer should never be “crash.”
- Can you deploy a new version without downtime? Docker image swap, PM2 reload, or rolling update.
- Could you hand this server to another developer? Is the README sufficient? Are the types clear? Are the tests comprehensive?
- Would you trust this server with real data? Input sanitization, auth, rate limiting, audit logging — are they all in place?
If the answer to all five questions is yes, you have built a production-grade MCP server. Congratulations — you have completed the curriculum.
Key Takeaway
Building a real-world MCP server means bringing together everything: protocol knowledge, design patterns, error handling, security, testing, and deployment. The capstone is not about building something complex — it is about building something complete. A server with three well-designed tools, proper error handling, tests, and documentation is worth more than a server with twenty tools and no tests. Ship something you would actually use, and you have truly mastered MCP server development.