MCP Best Practices

Design principles, security checklist, performance optimization, testing strategies, and frequently asked questions.

Server Design Principles

1. Single Responsibility

   Each MCP server should focus on one domain. A filesystem server handles files. A database server handles queries. Do not combine unrelated functionality.

2. Minimal Permissions

   Request only the access your server needs. A read-only analytics server should not have write permissions to the database.

3. Clear Tool Descriptions

   Write tool names and descriptions that the AI model can understand. The model uses these to decide when and how to call your tools.

4. Graceful Error Handling

   Return helpful error messages with isError: true rather than crashing. The AI model can use error messages to adjust its approach.

5. Idempotent Operations

   Where possible, design tools so calling them multiple times with the same arguments produces the same result.

Tool Naming Conventions

Security Checklist

Error Handling Patterns

// Good: Return descriptive errors the AI can act on
server.tool("query_db", "Execute SQL query", schema, async (args) => {
  try {
    const result = await db.query(args.sql);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  } catch (err) {
    if (err.code === "42P01") {
      return {
        content: [{ type: "text", text:
          `Table not found. Available tables: ${await listTables()}`
        }],
        isError: true
      };
    }
    return {
      content: [{ type: "text", text: `Query error: ${err.message}` }],
      isError: true
    };
  }
});

Performance Optimization

• Connection pooling: Reuse database connections rather than opening new ones for each tool call.
• Caching: Cache resource responses that change infrequently. Invalidate on resource update notifications.
• Pagination: For tools that return large result sets, support limit and offset parameters.
• Timeouts: Set reasonable timeouts for external API calls and database queries. Return an error rather than hanging.
• Lazy loading: Only initialize heavy dependencies (database connections, API clients) when first needed.

Testing Strategies

1. Unit Tests

   Test tool handler functions in isolation. Mock external dependencies (databases, APIs). Verify input validation and error handling.

2. Integration Tests

   Test the full MCP protocol flow. Use the MCP SDK's test client to send requests and verify responses.

3. MCP Inspector

   Use npx @modelcontextprotocol/inspector for interactive testing during development. Verify tools, resources, and prompts work correctly.

4. End-to-End Tests

   Connect your server to Claude Desktop or another client and verify it works in a real conversation.

Documentation Standards

Good documentation helps users and AI models understand your server:

• README: Include installation, configuration, and quick start instructions.
• Tool descriptions: Write as if explaining to someone who has never seen your API. Include examples of valid inputs.
• Parameter descriptions: Explain what each parameter does, its format, valid values, and defaults.
• Error documentation: List common errors and how to resolve them.

Frequently Asked Questions

Community Contribution Guidelines

If you build an MCP server for the community:

• Follow the naming convention: mcp-server-{domain} (e.g., mcp-server-weather).
• Publish to npm (@your-org/mcp-server-{domain}) or PyPI (mcp-server-{domain}).
• Include a clear README with installation, configuration, and usage examples.
• Add the mcp and model-context-protocol keywords/tags for discoverability.
• Test with the MCP Inspector and at least one real client (Claude Desktop, Cline, etc.).
• Include a LICENSE file (MIT is common in the ecosystem).