MCP Server Rules
These rules ensure consistent, secure, and maintainable MCP servers for the ecosystem. Following these guidelines helps create a better experience for both developers and users.
API Design
Guidelines for creating consistent and intuitive APIs
RESTful Endpoints
Design endpoints following REST principles with resources as nouns and HTTP methods for actions.
Versioning
Include API version in URL path (e.g., /v1/resource) to ensure backward compatibility.
Status Codes
Use appropriate HTTP status codes: 200 for success, 400 for client errors, 500 for server errors.
Error Responses
Return consistent error objects with 'error', 'message', and 'code' fields.
Pagination
Support pagination with limit/offset parameters for endpoints returning multiple items.
Filtering
Allow filtering resources by common attributes using query parameters.
Security
Practices for ensuring secure MCP server implementations
Authentication
Support token-based authentication with secure token storage and transmission.
Input Validation
Validate and sanitize all user inputs to prevent injection attacks and data corruption.
Rate Limiting
Implement rate limiting to prevent abuse and ensure fair resource usage.
HTTPS Only
Always use HTTPS for all communications to ensure data privacy and integrity.
Minimal Permissions
Request only the minimum permissions needed for functionality.
Secrets Management
Never hardcode secrets. Use environment variables or secure vaults for credentials.
Performance
Optimizations for responsive and efficient MCP servers
Response Time
Aim for sub-500ms response times for typical operations to ensure good user experience.
Caching
Implement appropriate caching with proper cache headers for improved performance.
Compression
Enable gzip/brotli compression for responses to reduce bandwidth usage.
Efficient Queries
Optimize database queries and avoid N+1 query problems for better scaling.
Connection Pooling
Use connection pooling for database and external service connections.
Asynchronous Processing
Use async processing for computationally intensive or long-running tasks.
Documentation
Standards for clear and comprehensive documentation
OpenAPI Specification
Provide OpenAPI/Swagger documentation for all endpoints with examples.
Getting Started
Include a clear getting started guide with installation and basic usage examples.
Error Reference
Document all possible error codes with explanations and resolution steps.
Versioning Policy
Clearly document your versioning policy and deprecation timeline.
Authentication Guide
Provide detailed steps for authentication setup and token management.
Changelog
Maintain a detailed changelog with all API changes, additions, and deprecations.
Compatibility
Ensuring broad compatibility across the MCP ecosystem
Language Support
Provide client libraries or examples for major programming languages.
Framework Integration
Document integration with popular AI frameworks and environments.
Backward Compatibility
Maintain backward compatibility within the same major version number.
Feature Detection
Use feature detection instead of version checking for capability determination.
Standards Compliance
Follow relevant industry standards and conventions for interoperability.
Cross-Platform
Ensure functionality works consistently across different operating systems.