Server crashes with "Server does not support completions" error on startup

Firecrawl MCP Server Crashing with "Server does not support completions" Error

The firecrawl-mcp-server was experiencing a critical issue where it would immediately crash upon startup with the error message "Server does not support completions (required for completion/complete)". This prevented the server from functioning as an MCP server within environments like Claude Code and Claude Desktop, effectively blocking integrations that rely on the Model Context Protocol.

Root Cause Analysis

The root cause of this issue stemmed from a version incompatibility within the @modelcontextprotocol/sdk dependency. The package-lock.json file specified version 1.18 of the SDK. However, due to inconsistencies in dependency resolution during installation (especially when using npx), a newer version (1.22) was sometimes being installed. Version 1.22 introduced stricter requirements, specifically the expectation that all MCP servers would support the "completions" capability. Firecrawl MCP, in certain configurations or older versions, may not have fully implemented this capability, leading to the crash.

The FastMCPSession class within the firecrawl-fastmcp package attempts to set up completion handlers. If the underlying MCP server (provided by @modelcontextprotocol/sdk) doesn't advertise support for completions, the assertRequestHandlerCapability function throws an error, halting the server's initialization process.

Solution

The immediate solution was to pin the @modelcontextprotocol/sdk dependency to the known working version (1.18) within the firecrawl-fastmcp fork. This ensured that the correct version of the SDK was consistently installed, preventing the incompatibility issue.

The recommended steps to resolve the issue are as follows:

1. Update Firecrawl MCP: Ensure you are using the latest version of firecrawl-mcp (version 3.6.1 or later). This version includes the fix for the dependency issue.
2. Reinstall: Completely reinstall the firecrawl-mcp package to guarantee that the updated dependencies are correctly fetched. If you installed globally, run these commands:

   npm uninstall -g firecrawl-mcp
   npm install -g firecrawl-mcp
   

   If you are using npx, the next time you run npx firecrawl-mcp, it should use the corrected version.

Important Considerations and Best Practices

• Dependency Management: This incident highlights the importance of strict dependency management in Node.js projects. Using npm shrinkwrap or npm ci (in production environments) can help ensure consistent dependency resolution across different environments.
• Version Pinning: While pinning dependencies can prevent immediate issues, it's crucial to regularly review and update dependencies to benefit from bug fixes, security patches, and performance improvements. However, always test thoroughly after updating.
• MCP Protocol Compliance: Ensure that your MCP server implementation fully complies with the required capabilities of the Model Context Protocol, especially if you intend to support features like code completion.
• Testing: Implement thorough integration tests that cover the core MCP functionality to detect such compatibility issues early in the development cycle. These tests should simulate real-world scenarios, including interactions with different MCP clients.

By following these best practices, you can minimize the risk of encountering similar dependency-related issues in the future and ensure the stability and reliability of your firecrawl-mcp-server deployments.