Awesome MCP Best Practices

A curated and opinionated list of awesome Model Context Protocol (MCP) best practices as they pertain to building MCP Servers and MCP Clients.

MCP Servers

• 1 MCP Server Tools
  • 1.1 Tool Naming Standards
  • 1.2 Tool Naming Aliases
  • 1.3 Tool Description Standards
  • 1.4 Avoid Not Found Responses
• 2 MCP Server Definition
  • 2.1 Provide Rich Server Instructions
• 3 MCP Server Architecture
  • 3.1 Abstract Server Capabilities
  • 3.2 Dont Map 1:1 APIs to Tools
• MCP Server Testing
• MCP Server Deployment
  • Package Your MCP Server as a Docker Container
• MCP Server Security
  • Secure MCP Server Code
  • Secure MCP Server Dependencies
  • Avoid descriptive errors
• MCP Server Performance
  • Cache costly Tools
• MCP Server Errors and Observability
  • Graceful timeouts

MCP Clients

// TBD

1 MCP Server Tools

🔵 1.1 Tool Naming Standards

Use consistent, compatible naming conventions for your MCP Server Tools to ensure they can be properly discovered and invoked by MCP Clients.

❌ Avoid These Tool Naming Conventions

• Spaces: get Npm Package Info
• Dot notation: get.Npm.Package.Info
• Brackets/parentheses: get(Npm)PackageInfo

✅ Recommended Tool Naming Conventions

• ✅ camelCase (preferred): getNpmPackageInfo
• kebab-case: get-npm-package-info
• snake_case: get_npm_package_info

server.tool(
  "getNpmPackageInfo",
  "Get information about an npm package",
  {
    packageName: z.string()
  },
  async ({ packageName }) => {    
    // Implementation details...
    return {
      content: [{ type: "text", text: output }],
    };
  }
);

💡 Why It Matters

Using non-standard naming conventions can prevent or disrupt MCP Clients from properly discovering and surfacing your tools to end users. GPT-4o tokenization works best with camelCase naming conventions.

🔵 1.2 Tool Naming Aliases

When the Tool name can be intereted and accessed using different naming conventions, call out aliases in the Tool's description.

❌ Problematic Pattern

For example, a postMesage tool name might be too specific:

server.tool(
  "postMessage",
  "Post a message under your account",
   () => {}
)

The LLM might not invoke the tool if the users ask for "share a social post on Twitter", or "upload this picture to Instagram".

✅ Recommended Practice

Specify aliases and elaborate description for LLMs to better understand when it is required to invoke your tool.

server.tool(
  "postMessage",
  "Upload, share, and post messages on social media",
   () => {}
)

🔵 1.3 Tool Description Standards

Even with large content windows, choosing the right tool to call, especially when many tools are exposed, will be a difficult task for an LLM. Providing as much context as possible within the description of tools is necessary and helpful.

❌ Avoid These Tool Description Conventions

Short description such as "Call this function to execute an SQL query"

✅ Recommended Tool Description Conventions

• Provide a use-case example reference
• Add necessary notes and nuances relevant to the tool

server.tool(
  "runSqlQuery",
  `<use_case>Use this tool to execute a single SQL query against a Postgres database.</use_case>
   <important_notes>
     If you have a temporary branch from a prior step, you MUST:
     1. Pass the branch ID to this tool unless explicitly told otherwise
     2. Tell the user that you ar eusing

... [View full README on GitHub](https://github.com/lirantal/awesome-mcp-best-practices#readme)