Skip to content
Back to search

awesome-mcp-best-practices

Build Awesome MCPs with Awesome Best Practices for MCP Servers and MCP Clients

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lirantal--awesome-mcp-best-practices/badge.svg)](/listings/lirantal--awesome-mcp-best-practices)

HTML

<a href="/listings/lirantal--awesome-mcp-best-practices"><img src="/api/listings/lirantal--awesome-mcp-best-practices/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 371 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Awesome MCP Best Practices ![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)
  2. A curated and opinionated list of awesome Model Context Protocol (MCP) best practices as they pertain to building MCP Servers and MCP Clients.
  3. ---
  4. ## MCP Servers
  5. - 1 MCP Server Tools
  6. - 1.1 [Tool Naming Standards](#-11-Tool-Naming-Standards)
  7. - 1.2 [Tool Naming Aliases](#-12-Tool-Naming-Aliases)
  8. - 1.3 [Tool Description Standards](#-13-tool-description-standards)
  9. - 1.4 [Avoid Not Found Responses](#-14-avoid-not-found-responses)
  10. - 2 MCP Server Definition
  11. - 2.1 [Provide Rich Server Instructions](#-21-provide-rich-server-instructions)
  12. - 3 MCP Server Architecture
  13. - 3.1 [Abstract Server Capabilities](#-31-abstract-server-capabilities)
  14. - 3.2 [Dont Map 1:1 APIs to Tools](#-32-dont-map-11-apis-to-tools)
  15. - MCP Server Testing
  16. - MCP Server Deployment
  17. - [Package Your MCP Server as a Docker Container](#-package-your-mcp-server-as-a-docker-container)
  18. - MCP Server Security
  19. - [Secure MCP Server Code](#-secure-mcp-server-code)
  20. - [Secure MCP Server Dependencies](#-secure-mcp-server-dependencies)
  21. ## MCP Clients
  22. // TBD
  23. ---
  24. ## 1 MCP Server Tools
  25. ### 🔵 1.1 Tool Naming Standards
  26. Use consistent, compatible naming conventions for your MCP Server `Tools` to ensure they can be properly discovered and invoked by MCP Clients.
  27. #### ❌ Avoid These Tool Naming Conventions
  28. - Spaces: `get Npm Package Info`
  29. - Dot notation: `get.Npm.Package.Info`
  30. - Brackets/parentheses: `get(Npm)PackageInfo`
  31. #### ✅ Recommended Tool Naming Conventions
  32. - ✅ camelCase (**preferred**): `getNpmPackageInfo`
  33. - kebab-case: `get-npm-package-info`
  34. - snake_case: `get_npm_package_info`
  35. ```javascript
  36. server.tool(
  37. "getNpmPackageInfo",
  38. "Get information about an npm package",
  39. {
  40. packageName: z.string()
  41. },
  42. async ({ packageName }) => {
  43. // Implementation details...
  44. return {
  45. content: [{ type: "text", text: output }],
  46. };
  47. }
  48. );
  49. ```
  50. #### 💡 Why It Matters
  51. 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.
  52. ---
  53. ### 🔵 1.2 Tool Naming Aliases
  54. When the Tool name can be intereted and accessed using different naming conventions, call out aliases in the Tool's description.
  55. #### ❌ Problematic Pattern
  56. For example, a `postMesage` tool name might be too specific:
  57. ```javascript
  58. server.tool(
  59. "postMessage",
  60. "Post a message under your account",
  61. () => {}
  62. )
  63. ```
  64. The LLM might not invoke the tool if the users ask for "share a social post on Twitter", or "upload this picture to Instagram".
  65. #### ✅ Recommended Practice
  66. Specify aliases and elaborate description for LLMs to better understand when it is required to invoke your tool.
  67. ```javascript
  68. server.tool(
  69. "postMessage",
  70. "Upload, share, and post messages on social media",
  71. () => {}
  72. )
  73. ```
  74. ---
  75. ### 🔵 1.3 Tool Description Standards
  76. 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.
  77. #### ❌ Avoid These Tool Description Conventions
  78. Short description such as "Call this function to execute an SQL query"
  79. #### ✅ Recommended Tool Description Conventions
  80. - Provide a use-case example reference
  81. - Add necessary notes and nuances relevant to the tool
  82. ```javascript
  83. server.tool(
  84. "runSqlQuery",
  85. `<use_case>Use this tool to execute a single SQL query against a Postgres database.</use_case>
  86. <important_notes>
  87. If you have a temporary branch from a prior step, you MUST:
  88. 1. Pass the branch ID to this tool unless explicitly told otherwise
  89. 2. Tell the user that you ar eusing the temporary branch with ID [branch_id]
  90. </important_notes>
  91. `
  92. );
  93. ```
  94. #### 💡 Why It Matters
  95. 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.
  96. ---
  97. ### 🔵 1.4 Avoid Not Found Responses
  98. When implementing search-type tools in your MCP Server, avoid returning explicit "not found" messages even when exact matches aren't available.
  99. #### ❌ Problematic Pattern
  100. ```javascript
  101. // Don't do this
  102. if (!exactMatch) {
  103. return {
  104. content: [
  105. {
  106. type: "text",
  107. text: `Module ${query} not found. Here are all available modules: ${allModules}`
  108. }
  109. ]
  110. };
  111. }
  112. ````
  113. #### ✅ Recommended Practice
  114. ```javascript
  115. // Do this instead
  116. return {
  117. content: [
  118. {
  119. type: "text",
  120. text: `Here are the available modules that may help with your query: ${relevantModules}`
  121. }
  122. ]
  123. };
  124. ```
  125. #### 💡 Why It Matters
  126. Let the LLM determine relevance from the data provided rather than prematurely declaring failure in your tool response. LLMs can be overly influenced by negative statements like "not found" causing them to ignore the useful information that follows. By providing relevant data without negative framing, you enable the LLM to process and utilize all available information properly.
  127. #### ⚠️ Important Exception
  128. This approach isn't appropriate for all scenarios. When handling sensitive data (like user information), security and privacy concerns should take precedence over providing alternative data.
  129. ---
  130. ## 2 MCP Server Definition
  131. ### 🔵 2.1 Provide Rich Server Instructions
  132. Provide a rich description of the MCP Server to clearly explain its purpose, how tools, resources and other capabilities should be mapped to workflows and actions. Enhance the description with best practices, and any other information that helps the LLM gain context on how to best use the MCP Server.
  133. #### ✅ Recommended Practice
  134. Example for rich instructions provided to the MCP Server, reference from [Graphlit MCP Server](https://github.com/graphlit/graphlit-mcp-server/blob/main/src/index.ts)
  135. ```js
  136. const DEFAULT_INSTRUCTIONS = `
  137. You are provided a set of MCP tools and resources that integrate with the [Graphlit](https://www.graphlit.com) Platform.
  138. To use each of the Graphlit MCP tools, there may be environment variables which are required to be configured in your MCP client. These are described in the description for each tool.
  139. These must be configured in the MCP client YAML or JSON configuration file before you can use the tools. *Do not* set these directly in your Terminal or shell environment.
  140. Graphlit is an LLM-enabled knowledge API platform, which supports these resources:
  141. - project: container for ingested contents, which can be configured with a default workflow
  142. - contents: all ingested files, web pages, messages, etc.; also includes short-term 'memory' contents
  143. - feeds: data connectors which ingest contents
  144. - collections: named groups of contents
  145. - conversations: chat message history of LLM conversation, which uses RAG pipeline for content retrieval
  146. - workflows: how content is handled during the ingestion process
  147. - specifications: LLM configuration presets, used by workflows and conversations
  148. Identifiers for all resources are unique within the Graphlit project, and are formatted as GUIDs.
  149. You have access to one and only one Graphlit project, which can optionally be configured with a workflow to guide the document preparation and entity extraction of ingested content.
  150. The Graphlit project is non-deletable, but you can create and delete contents, feeds, collections, conversations, specifications and workflows within the project.
  151. You can query the Graphlit project resource for the credits used, LLM tokens used, and the available project quota. By default, credits cost USD$0.10, and are discounted on higher paid tiers.
  152. With this Graphlit MCP Server, you can ingest anything from Slack, Discord, websites, Notion, Google Drive, email, Jira, Linear or GitHub into a Graphlit project - and then search and retrieve relevant knowledge within an MCP client like Cursor, Windsurf or Cline.
  153. Documents (PDF, DOCX, PPTX, etc.) and HTML web pages will be extracted to Markdown upon ingestion. Audio and video files will be transcribed upon ingestion.
  154. ## Best Practices:
  155. 1. Always look for matching resources before you try to call any tools.
  156. For example, "have i configured any graphlit workflows?", you should check for workflow resources before trying to call any other tools.
  157. 2. Don't use 'retrieveSources' to locate contents, when you have already added the contents into a collection. In that case, first retrieve the collection resource, which contains the content resources.
  158. 3. Only call the 'configureProject' tool when the user explicitly asks to configure their Graphlit project defaults.
  159. 4. Never infer, guess at or hallucinate any URLs. Always retrieve the latest content resources in order to get downloadable URLs.
  160. 5. Use 'ingestMemory' to save short-term memories, such as temporary notes or intermediate state for research. Use 'ingestText' to store long-term knowledge, such as Markdown results from research.
  161. 6. Always use 'PODSCAN' web search type when searching for podcast episodes, podcast appearances, etc.
  162. 7. Prioritize using feeds, rather than 'ingestUrl', when you want to ingest a website. Feeds are more efficient and faster than using 'ingestUrl'.
  163. If you receive a request to ingest a GitHub URL, use the 'ingestGitHubFiles' tool to ingest the repository, rather than using 'ingestUrl'.
  164. Always attempt to use the most-specific tool for the task at hand.
  165. ## Short-term vs Long-term Memory:
  166. You can perform scatter-gather operations where you save short-term memories after each workflow step, and then gather relevant memories prior to the moving onto the next step.
  167. Leverage short-term memories when evaluating the results of a workflow step, and then use long-term memories to store the final results of your workflow.
  168. You can collect memories in collections, and then use the 'queryContents' tool to retrieve the 'memory' contents by the collection. This will help you to keep track of your progress and avoid losing any important information.
  169. If you have any trouble with this Graphlit MCP Server, join our [Discord](https://discord.gg/ygFmfjy3Qx) community for support.
  170. `;
  171. export const server = new McpServer(
  172. {
  173. name: "Graphlit MCP Server",
  174. version: "1.0.0",
  175. },
  176. {
  177. instructions: DEFAULT_INSTRUCTIONS,
  178. }
  179. );
  180. ```
  181. ---
  182. ## 3 MCP Server Architecture
  183. ### 🔵 3.1 Abstract Server Capabilities
  184. Follow an inversion-of-control paradigm to allow your MCP Server capabilities to receive a `server` object and use it to apply `tools`, `resources`, `prompts`, and other capabilities.
  185. #### 💡 Why It Matters
  186. You may not know ahead of time if you will need to build for an STDIO or HTTP transports, nor you don't know which SDK or cloud infrastructure you will be deploying to (e.g: Vercel vs Cloudflare). To allow the underlying MCP Server logic implementation to supplement any of these future concerns, build it in a way that
  187. // TBD bad pattern
  188. // TBD good pattern
  189. // TBD example code
  190. ---
  191. ### 🔵 3.2 Dont Map 1:1 APIs to Tools
  192. Avoid mapping your traditional RESTful or GraphQL APIs in a 1:1 mapping with your Tools. This leads to poor experience for LLMs to drive high-level use-case scenarios.
  193. #### ❌ Avoid 1:1 API Mapping to Tools
  194. While mapping your APIs exactly as they are to tools definitions in an MCP server might seem like a quick low-hanging fruit, it introduces these problems and challenges:
  195. - Too many tools (as there are APIs, which often for a given application is counted in tens or more)
  196. - Too many tool calls leads to too many tokens
  197. - Tools become too fine-grained and LLMs need to perform several loops of tool calls to assemble one use-case action
  198. - How do you decide between different API versions and their tool targets?
  199. Case-study: [Notion API to MCP Tools story](https://x.com/NotionAPI/status/1955666043235692622)
  200. #### ✅ Recommended Tool Definitions
  201. - Define tools as high-level use-case scenarios that will be driven by LLMs
  202. #### 💡 Why It Matters
  203. You may
  204. ---
  205. ## MCP Server Deployment
  206. ### 🔵 Package Your MCP Server as a Docker Container
  207. Deploy your MCP Servers as Docker containers to eliminate environment setup challenges and ensure consistent operation across different systems.
  208. #### 💡 Why It Matters
  209. MCP Servers often require specific runtime environments (Node.js, Python) with particular versions and dependencies. Docker abstracts away these requirements, turning complex setup instructions into a simple container run command.
  210. #### 💪 Key Benefits
  211. - Consistency: Eliminates "works on my machine" problems
  212. - Isolation: Prevents dependency conflicts with host system
  213. - Portability: Runs identically across development, testing, and production
  214. - Simplified Deployment: Reduces user setup to installing Docker and running a container
  215. - Resource Management: Provides built-in tools for controlling CPU, memory, and network usage
  216. Example `Dockerfile` implementation to package an MCP Server
  217. ```
  218. FROM node:18-slim
  219. WORKDIR /app
  220. COPY package*.json ./
  221. RUN npm install
  222. COPY . .
  223. EXPOSE 3000
  224. CMD ["node", "server.js"]
  225. ```
  226. Users run it as follows:
  227. ```
  228. docker run -p 3000:3000 your-mcp-server-image
  229. ```
  230. ---
  231. ## MCP Server Security
  232. ### 🔵 Secure MCP Server Code
  233. An MCP tool's name, description and argument schema help clients call it correctly, but they do not replace security checks inside the server. Make the decision to permit an operation at the trusted server boundary.
  234. #### ✅ Recommended Practice
  235. - Validate tool arguments at tool-handler boundaries and resource URIs at resource-handler boundaries. Check the actual requested resource, file path, destination and operation against an explicit allowlist or other server-side policy; do not rely solely on client-supplied metadata.
  236. - Apply least-privilege access controls to every sensitive tool call. For HTTP servers that require authorization, validate access tokens for the intended resource and required scopes before dispatching protected operations.
  237. - Treat tool results and externally retrieved text as untrusted data. Do not interpret that content as instructions granting permission to call additional tools or disclose secrets.
  238. - Exercise both permitted and denied operations in tests, including invalid tool arguments, unauthorized resource access and insufficient scopes.
  239. For HTTP authorization patterns, consult the [MCP TypeScript SDK's server authorization guidance](https://ts.sdk.modelcontextprotocol.io/v2/serving/authorization). Authorization is an enforcement boundary, not a prompt or a tool description.
  240. ### 🔵 Secure MCP Server Dependencies
  241. Ensure your MCP Server is free from known vulnerabilities in third-party dependencies to meet security requirements and facilitate organizational adoption.
  242. #### 💡 Why It Matters
  243. MCP Servers typically require broad access and integration capabilities, making any vulnerability a significant security risk. Organizational IT and security teams scrutinize these dependencies before approving adoption.
  244. - MCP Servers must meet stringent security and compliance requirements
  245. - Vulnerable dependencies create potential entry points for malicious actors
  246. - Security is mandated by SBOM requirements following the SolarWinds attack
  247. #### ✅ Recommended Practice
  248. - Regularly scan dependencies for known vulnerabilities
  249. - Keep all components updated to the latest secure versions
  250. - Monitor security advisories related to your dependencies
  251. - Ensure compliance with licensing and security standards

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.