mcp-best-practices

MCP Best Practices - May 26, 2025

I. General Tool Configuration & Behavior

1. Sensible Defaults: All environment variables must have sensible defaults for easy out-of-the-box usage.
2. Dynamic Versioning: The tool's version is emitted in its description. This version must be read dynamically (e.g., from package.json) and not hardcoded.
3. Tool & Parameter Descriptions:
   • Tool Titles: Use descriptive, human-friendly titles for tools.
   • Parameter Descriptions: All parameters must offer a clear description.
   • Optional/Required Parameters: Parameters must be explicitly noted as "optional" or "required."
   • Default Values: If a parameter is optional, its default value must be explained.
   • (These details should be verifiable by hovering over the tool in clients like Cursor or using the MCP inspector.)
4. Parameter Parsing: Parameter parsing should be lenient (e.g., accept path if project_path is formally defined). Generally, advertise stricter schemas but be more lenient in execution to accommodate variations from agents.
5. Runtime Error Handling: In case of an error, emit a helpful message to the caller with information to potentially recover.
6. Configuration Error Handling: Misconfigurations (e.g., wrongly set environment variables) must not crash the tool. Instead, provide a useful explanation when the tool is run, enabling the user to self-correct their setup.
7. No stdio Output: CRITICAL: There must be absolutely NO output to stdout or stderr during any tool operation. This includes:
   • No console.log(), console.error(), console.warn(), etc.
   • No process.stdout.write() or process.stderr.write()
   • No print statements or debug output to stdio
   • Even during errors or initialization, all output must go through the file logger
   • Any stdio output will disrupt MCP clients (like Claude) and cause loading errors
   • File-based logging (e.g., Pino to log files) is the only acceptable method for operational output
8. info Command:
   • At least one tool must offer an info sub command (find the most appropriate tool and add there)
   • This command shall list:
     • The version of the MCP tool.
     • The status of any required native dependencies (if applicable), including tests for their presence and functionality.
     • Any detected configuration issues or missing environment variables (e.g., problems with the logger path).

II. Logging (Pino)

1. Default File Logger: Pino is used for logging with a default file logger in the system's log directory (e.g., ~/Library/Logs/). The log file path is configurable via the [ProjectName]_LOG_FILE environment variable.
2. Log Path Resilience:
   • Pino logic must automatically create missing parent directories for the specified log file path.
   • If pino cannot write to the [ProjectName]_LOG_FILE path, it must fall back to logging to the default temporary directory path.
3. Configurable Log Level: The log level is set using the [ProjectName]_LOG_LEVEL environment variable (accepts upper, lower, or mixed case values).
4. Optional Console Logging: An environment variable, [ProjectName]_CONSOLE_LOGGING=true, enables logging to the console in addition to the pino file logger.
5. Logger Flush: The logger must be flushed before the process exits to ensure all log messages are written.

III. Code, Dependencies & Build

1. Dependency Management: All dependencies should be kept at their latest stable versions. (The release script will warn for outdated dependencies).
2. Static Analysis: There must be no linter (e.g., ESLint) or TypeScript errors.
3. File Size: No single file should exceed 500 lines of code (LOC); aim for below 300 LOC.
4. Execution with Compiled Code: The startup logic and all tool operations must always use the compiled JavaScript output (e.g., from the dist folder).
5. Shebangs: Compiled JavaScript files intended for direct execution must have the correct shebang (e.g., #!/usr/bin/env node).
6. NPM Package Contents: The published npm package must contain only the absolute minimum files: the dist/ folder, any potential native components, the README.md, and a LICENSE file.