MCP Builder
Principles for building MCP servers.
1. MCP Overview
What is MCP?
Model Context Protocol - standard for connecting AI systems with external tools and data sources.
Core Concepts
| Concept | Purpose | |
|---|
| Tools | Functions AI can call | |
| Resources | Data AI can read | |
| Prompts | Pre-defined prompt templates | |
2. Server Architecture
Project Structure
my-mcp-server/
├── src/
│ └── index.ts # Main entry
├── package.json
└── tsconfig.json
Transport Types
| Type | Use | |
|---|
| Stdio | Local, CLI-based | |
| SSE | Web-based, streaming | |
| WebSocket | Real-time, bidirectional | |
3. Tool Design Principles
Good Tool Design
| Principle | Description | |
|---|
| Clear name | Action-oriented (get_weather, create_user) | |
| Single purpose | One thing well | |
| Validated input | Schema with types and descriptions | |
| Structured output | Predictable response format | |
Input Schema Design
| Field | Required? | |
|---|
| Type | Yes - object | |
| Properties | Define each param | |
| Required | List mandatory params | |
| Description | Human-readable | |
4. Resource Patterns
Resource Types
| Type | Use | |
|---|
| Static | Fixed data (config, docs) | |
| Dynamic | Generated on request | |
| Template | URI with parameters | |
URI Patterns
| Pattern | Example | |
|---|
| Fixed | docs://readme | |
| Parameterized | users://{userId} | |
| Collection | files://project/* | |
5. Error Handling
Error Types
| Situation | Response | |
|---|
| Invalid params | Validation error message | |
| Not found | Clear "not found" | |
| Server error | Generic error, log details | |
Best Practices
- Return structured errors
- Don't expose internal details
- Log for debugging
- Provide actionable messages
6. Multimodal Handling
Supported Types
| Type | Encoding | |
|---|
| Text | Plain text | |
| Images | Base64 + MIME type | |
| Files | Base64 + MIME type | |
7. Security Principles
Input Validation
- Validate all tool inputs
- Sanitize user-provided data
- Limit resource access
API Keys
- Use environment variables
- Don't log secrets
- Validate permissions
8. Configuration
Claude Desktop Config
| Field | Purpose | |
|---|
| command | Executable to run | |
| args | Command arguments | |
| env | Environment variables | |
9. Testing
Test Categories
| Type | Focus | |
|---|
| Unit | Tool logic | |
| Integration | Full server | |
| Contract | Schema validation | |
10. Best Practices Checklist
- [ ] Clear, action-oriented tool names
- [ ] Complete input schemas with descriptions
- [ ] Structured JSON output
- [ ] Error handling for all cases
- [ ] Input validation
- [ ] Environment-based configuration
- [ ] Logging for debugging
Remember: MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.