Awesome MCP Best Practices

The project is a reference guide, not an installable package. Browse the README at https://github.com/lirantal/awesome-mcp-best-practices to read through all sections before writing any code.

git clone https://github.com/lirantal/awesome-mcp-best-practices.git
cd awesome-mcp-best-practices

The guide recommends camelCase tool names with clear, descriptive identifiers. Provide tool aliases so LLMs can discover them via alternate phrasings. Avoid vague names like 'run' or 'execute'.

// Good: camelCase with descriptive name
server.tool('searchDocuments', { query: z.string() }, handler)
// Add aliases for discoverability
server.tool('findDocuments', { query: z.string() }, handler)

Every tool should have a detailed description explaining what it does, when to use it, and what parameters mean. LLMs use these descriptions for tool selection — thin descriptions lead to wrong tool choices.

server.tool(
  'executeQuery',
  'Runs a read-only SQL query against the production database and returns results as JSON. Use this when the user asks for data, reports, or counts. Do NOT use for INSERT/UPDATE/DELETE.',
  { sql: z.string().describe('A valid read-only SQL SELECT statement') },
  handler
)

Return meaningful error messages instead of empty responses or raw stack traces. The guide warns against 'not found' responses that give the LLM nothing to act on. Include context about what failed and why.

Follow the guide's Dockerfile pattern to containerize your server. This ensures consistent runtime behavior across environments and simplifies deployment for end users.

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
CMD ["node", "dist/index.js"]

The guide emphasizes regular vulnerability scanning of your MCP server's dependencies before publishing. Run npm audit or a dedicated scanner as part of your CI pipeline.

npm audit
npx audit-ci --moderate