[BUG]: Quick start issue - cannot import name 'McpError' from 'mcp'

[tanushreepaul04]

🐞 Bug Summary

cannot import name 'McpError' from 'mcp'
got that error when tried to run mcpgateway.exe --host 0.0.0.0 --port 4444

In Windows, I was trying to follow Quick Start instructions with uv commands

On google search found this
"This import failure occurs because the mcp Python SDK updated to version 2.0.0, which renamed the McpError exception class to MCPError "

It really resolved after I pinned that mcp server to "mcp>=1.1.3,<2.0.0"

🧩 Affected Component

Select the area of the project impacted:

• [ x] mcpgateway - API
• [ x] mcpgateway - UI (admin panel)
• mcpgateway.wrapper - stdio wrapper
• Federation or Transports
• CLI, Makefiles, or shell scripts
• Container setup (Docker/Podman/Compose)
• Other (explain below)

---

🔁 Steps to Reproduce

1. ...Follow Windows Quick start with uv
2. ...
3. ...

---

🤔 Expected Behavior

What should have happened instead?

After installation mcpgateway.exe --host 0.0.0.0 --port 4444 should start the mcp gateway

📓 Logs / Error Output

Paste any relevant stack traces or logs here.
⚠️ Do not paste secrets, credentials, or tokens.

cannot import name 'McpError' from 'mcp'

🧠 Environment Info

You can retrieve most of this from the /version endpoint.

Key	Value
Version or commit	e.g. v0.9.0 or main@a1b2c3d
Runtime	e.g. Python 3.11, Gunicorn
Platform / OS	e.g. Ubuntu 22.04, macOS
Container	e.g. Docker, Podman, none

---

🧩 Additional Context (optional)

Add any configuration details, flags, or related issues.

[ebarkhordar]

Reproduced on a clean python:3.12-slim container, installing the current PyPI release the way the Quick Start does:

$ pip install "mcp-contextforge-gateway==1.0.6"
$ pip show mcp | grep Version
Version: 2.0.0
$ mcpgateway --host 0.0.0.0 --port 4444
...
  File "/usr/local/lib/python3.12/site-packages/cpex/framework/external/mcp/client.py", line 24, in <module>
    from mcp import ClientSession, McpError, StdioServerParameters
ImportError: cannot import name 'McpError' from 'mcp' (/usr/local/lib/python3.12/site-packages/mcp/__init__.py). Did you mean: 'MCPError'?

Your diagnosis is right, and the dates are the whole story:

• mcp-contextforge-gateway 1.0.6 was published 2026-07-21, and its metadata declares mcp>=1.28.1 with no upper bound.
• mcp 2.0.0 stable was published 2026-07-28 and dropped the McpError alias. python -c 'import mcp; print("McpError" in dir(mcp), "MCPError" in dir(mcp))' prints False True.

So any fresh install of the latest release since 2026-07-28 resolves mcp 2.0.0 and dies at import. It is not Windows specific; the run above is Linux.

The cap is already on main. Commit 91f8920c2 (PR #5840, closing #5839) changed "mcp>=1.28.1" to "mcp>=1.28.1,<2" at pyproject.toml:142 on 2026-07-27, one day before mcp 2.0.0 shipped. git tag --contains 91f8920c2 comes back empty, so it is in no released version yet, which is why a uv or pip Quick Start still hits it.

One detail that might matter when you decide the fix: the failing frame is inside cpex, not mcpgateway, and cpex 0.1.2 also declares mcp>=1.26.0 uncapped. Since pip resolves a single mcp for the environment, the gateway's own <2 is enough to hold it down. I mention it only because anyone reading the traceback lands in a different package and may go looking there.

Your workaround checks out, same container:

$ pip install "mcp-contextforge-gateway==1.0.6" "mcp<2"
$ pip show mcp | grep Version
Version: 1.29.0
$ mcpgateway --host 0.0.0.0 --port 4444
(boots, runs the migrations, serves)

If a release carrying the pin is not close, a line on the Quick Start page may save some tickets, since this reads like a broken install rather than a resolver picking up a new major.

[jonpspri]

Thanks for the report, @tanushreepaul04!

This is no longer reproducible with the current codebase. The dependency pin in pyproject.toml already constrains the MCP SDK to mcp>=1.28.1,<2, which is exactly the workaround you identified — the <2 upper bound prevents mcp 2.0.0 (which renamed McpError → MCPError) from being installed.

Anyone following the Quick Start with uv today will get mcp 1.x and the import will succeed as expected.

Closing as resolved.