mcp_best_practices

Follow these standardized naming patterns:

MCP Server Best Practices

Quick Reference

Server Naming

• Python: {service}_mcp (e.g., slack_mcp)
• Node/TypeScript: {service}-mcp-server (e.g., slack-mcp-server)

Tool Naming

• Use snake_case with service prefix
• Format: {service}_{action}_{resource}
• Example: slack_send_message, github_create_issue

Response Formats

• Support both JSON and Markdown formats
• JSON for programmatic processing
• Markdown for human readability

Pagination

• Always respect limit parameter
• Return has_more, next_offset, total_count
• Default to 20-50 items

Transport

• Streamable HTTP: For remote servers, multi-client scenarios
• stdio: For local integrations, command-line tools
• Avoid SSE (deprecated in favor of streamable HTTP)

---

Server Naming Conventions

Follow these standardized naming patterns:

Python: Use format {service}_mcp (lowercase with underscores)

• Examples: slack_mcp, github_mcp, jira_mcp

Node/TypeScript: Use format {service}-mcp-server (lowercase with hyphens)

• Examples: slack-mcp-server, github-mcp-server, jira-mcp-server

The name should be general, descriptive of the service being integrated, easy to infer from the task description, and without version numbers.

---

Tool Naming and Design

Tool Naming

1. Use snake_case: search_users, create_project, get_channel_info
2. Include service prefix: Anticipate that your MCP server may be used alongside other MCP servers

• Use slack_send_message instead of just send_message
• Use github_create_issue instead of just create_issue

1. Be action-oriented: Start with verbs (get, list, search, create, etc.)
2. Be specific: Avoid generic names that could conflict with other servers

Tool Design

• Tool descriptions must narrowly and unambiguously describe functionality
• Descriptions must precisely match actual functionality
• Provide tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
• Keep tool operations focused and atomic

---

Response Formats

All tools that return data should support multiple formats:

JSON Format (response_format="json")

• Machine-readable structured data
• Include all available fields and metadata
• Consistent field names and types
• Use for programmatic processing

Markdown Format (response_format="markdown", typically default)

• Human-readable formatted text
• Use headers, lists, and formatting for clarity
• Convert timestamps to human-readable format
• Show display names with IDs in parentheses
• Omit verbose metadata

---

Pagination

For tools that list resources:

• Always respect the limit parameter
• Implement pagination: Use offset or cursor-based pagination
• Return pagination metadata: Include has_more, next_offset/next_cursor, total_count
• Never load all results into memory: Especially important for large datasets
• Default to reasonable limits: 20-50 items is typical

Example pagination response:

{
  "total": 150,
  "count": 20,
  "offset": 0,
  "items": [...],
  "has_more": true,
  "next_offset": 20
}

---

Transport Options

Streamable HTTP

Best for: Remote servers, web services, multi-client scenarios

Characteristics:

• Bidirectional communication over HTTP
• Supports multiple simultaneous clients
• Can be deployed as a web service
• Enables server-to-client notifications

Use when:

• Serving multiple clients simultaneously
• Deploying as a cloud service
• Integration with web applications

stdio

Best for: Local integrations, command-line tools

Characteristics:

• Standard input/output stream communication
• Simple setup, no network configuration needed
• Runs as a subprocess of the client

Use when:

• Building tools for local development environments
• Integrating with desktop applications
• Single-user, single-session scenarios

Note: stdio servers should NOT log to stdout (use stderr for logging)

Transport Selection

| Criterion | stdio | Streamable HTTP | |-----------|-------|-----------------| | Deployment | Local | Remote | | Clients | Single | Multiple | | Complexity | Low | Medium | | Real-time | No | Yes |

---

Security Best Practices

Authentication and Authorization

OAuth 2.1:

• Use secure OAuth 2.1 with certificates from recognized authorities
• Validate access tokens before processing requests
• Only accept tokens specifically intended for your server

API Keys:

• Store API keys in environment variables, never in code
• Validate keys on server startup
• Provide clear error messages when authentication fails

Input Validation

• Sanitize file paths to prevent directory traversal
• Validate URLs and external identifiers
• Check parameter sizes and ranges
• Prevent command injection in system calls
• Use schema validation (Pydantic/Zod) for all inputs

Error Handling

• Don't expose internal errors to clients
• Log security-relevant errors server-side
• Provide helpful but not revealing error messages
• Clean up resources after errors

DNS Rebinding Protection

For streamable HTTP servers running locally:

• Enable DNS rebinding protection
• Validate the Origin header on all incoming connections
• Bind to 127.0.0.1 rather than 0.0.0.0

---

Tool Annotations

Provide annotations to help clients understand tool behavior:

| Annotation | Type | Default | Description | |-----------|------|---------|-------------| | readOnlyHint | boolean | false | Tool does not modify its environment | | destructiveHint | boolean | true | Tool may perform destructive updates | | idempotentHint | boolean | false | Repeated calls with same args have no additional effect | | openWorldHint | boolean | true | Tool interacts with external entities |

Important: Annotations are hints, not security guarantees. Clients should not make security-critical decisions based solely on annotations.

---

Error Handling

• Use standard JSON-RPC error codes
• Report tool errors within result objects (not protocol-level errors)
• Provide helpful, specific error messages with suggested next steps
• Don't expose internal implementation details
• Clean up resources properly on errors

Example error handling:

try {
  const result = performOperation();
  return { content: [{ type: "text", text: result }] };
} catch (error) {
  return {
    isError: true,
    content: [{
      type: "text",
      text: `Error: ${error.message}. Try using filter='active_only' to reduce results.`
    }]
  };
}

---

Testing Requirements

Comprehensive testing should cover:

• Functional testing: Verify correct execution with valid/invalid inputs
• Integration testing: Test interaction with external systems
• Security testing: Validate auth, input sanitization, rate limiting
• Performance testing: Check behavior under load, timeouts
• Error handling: Ensure proper error reporting and cleanup

---

Documentation Requirements

• Provide clear documentation of all tools and capabilities
• Include working examples (at least 3 per major feature)
• Document security considerations
• Specify required permissions and access levels
• Document rate limits and performance characteristics