| name | mcp-builder |
| description | MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices. |
| when_to_use | When building MCP (Model Context Protocol) servers, designing MCP tools, or implementing MCP resource patterns. |
| allowed-tools | Read, Write, Edit, Glob, Grep |
| version | 1.0.0 |
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 — McpServer from @modelcontextprotocol/sdk
├── package.json # dep: @modelcontextprotocol/sdk
└── tsconfig.json
TypeScript SDK: @modelcontextprotocol/sdk (McpServer). Python SDK: mcp (pip install "mcp[cli]", FastMCP bundled in mcp.server.fastmcp).
Transport Types
| Type | Use |
|---|
| stdio | Local, CLI-based |
| Streamable HTTP | Remote/web servers (replaced the deprecated HTTP+SSE transport) |
The current spec (2025-06-18) defines two standard transports: stdio and Streamable HTTP. WebSocket is not a standard transport. Validate the Origin header on Streamable HTTP servers.
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
Client Config (Claude Desktop, Claude Code, IDEs)
| Field | Purpose |
|---|
| command | Executable to run (stdio servers) |
| args | Command arguments |
| env | Environment variables |
MCP is multi-client — the same server works across Claude Desktop, Claude Code, and IDE hosts. Remote (Streamable HTTP) servers authenticate via OAuth rather than a local command.
9. Current Spec Features
Worth using in modern servers (spec 2025-06-18):
| Feature | Purpose |
|---|
| Tool annotations | Hint read-only/destructive behavior to the client |
Structured content / outputSchema | Typed, predictable tool results |
| Resource links | Return references to resources from tool results |
| OAuth | Auth for remote/Streamable HTTP servers |
10. Testing
Test Categories
| Type | Focus |
|---|
| Unit | Tool logic |
| Integration | Full server |
| Contract | Schema validation |
11. Best Practices Checklist
Remember: MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.
