Announcement: V2 Breaking Changes for Library Usage of mongodb-mcp-server

[gagik]

Hey all,

In case you weren't aware, it’s currently possible to use the mongodb-mcp-server package as a library for creating custom, MongoDB-powered MCP servers. While we don’t have exact usage numbers, we’ve found that using a single package for both the user-facing executable and the extendable library causes several issues, such as pulling in CLI-specific dependencies that don't make sense for other environments. We’ve also evolved the codebase significantly and, while we've tried to keep the API stable, we have deprecated a large number of methods.

Consequently, we are planning to introduce v2 of the MongoDB MCP library. This version will include a few breaking changes, such as:

• Splitting MCP server components into smaller packages (e.g., @mongodb-js/mcp-transport).
• Streamlining various structures used by the library.
• Better reorganizing how we separate the user-facing executable from the library code.

---

If you use mongodb-mcp-server via CLI or Docker

If you simply run the server via agentic tools/ IDEs (e.g. Claude Code, Cursor, GitHub Copilot), npx mongodb-mcp-server or Docker, nothing will change. The user-facing executable API will be kept as is, and no migration is necessary.

If you use mongodb-mcp-server as a library

If you use the package as a library to build custom MCP servers and want to access the latest features in v2, you will likely need to migrate. We will publish a full migration guide as we get closer to the release date.

We want your input! Please share your feedback if there’s anything specific you’d like to see improved in the library usage experience.