MCP Builder
Principles for building MCP servers.
- 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
- 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
- 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
- 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/*
- 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
- Multimodal Handling
Supported Types
Type Encoding
Text Plain text
Images Base64 + MIME type
Files Base64 + MIME type
- 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
- Configuration
Claude Desktop Config
Field Purpose
command Executable to run
args Command arguments
env Environment variables
- Testing
Test Categories
Type Focus
Unit Tool logic
Integration Full server
Contract Schema validation
- 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.