[BUG] Minimal dependency check fails on every PR: mcp 2.x removed FastMCP and `mcp>=1.3.0` is unbounded

[JessYanCoding]

Required prerequisites

• I have read the documentation https://camel-ai.github.io/camel/camel.html.
• I have searched the Issue Tracker and Discussions that this hasn't already been reported.

On the search: this was reported before, in #4246, with a fix proposed in
#4247; both were closed on 2026-07-31. I am filing again because the situation
has changed since then — the break now fails CI on every pull request, and on
master — and because I ran into it independently on my own PR (#4292) rather
than from those threads. If the earlier closure already reflected a decision
against capping mcp, please just close this; I would rather ask than assume.

What version of camel are you using?

0.2.91a5 (current master, 13dc7a7)

System information

• Installed from source with pip install -e . in a clean Python 3.11 venv
  (CI uses 3.10 and shows the same failure)
• camel 0.2.91a5
• Resolved mcp version: 2.1.0

Problem description

camel/toolkits/base.py:68 does from mcp.server import FastMCP inside the
BaseToolkit class body. mcp 2.x removed FastMCP entirely — the string
FastMCP does not appear anywhere in the 2.1.0 wheel (0 files, 0 occurrences);
mcp.server now exports MCPServer instead.

pyproject.toml:24 pins mcp>=1.3.0 with no upper bound (same in the
dev_tools and all extras). uv.lock resolves mcp==1.28.1, so every
uv-based install is fine — which is why this is invisible in local development.
Any install that does not use the lock resolves to mcp 2.1.0, and importing
camel.agents, camel.societies or camel.societies.workforce fails.

What is newly broken. The Minimal dependency check job installs with plain
pip install -e ., so it hits this. Its last 8 runs, across 6 unrelated
branches and several authors, are all failures:

2026-08-25  ca4711a3  fix/stream-cumulative-repeat   failure
2026-08-25  82b2b0bc  feat/chat-agent-max-tool-cal   failure
2026-08-25  a7b19e17  feat/chat-agent-max-tool-cal   failure
2026-08-25  4a356ce9  fix/deepseek-reasoning-cache   failure
2026-08-25  aa81e5d1  fix/deepseek-reasoning-cache   failure
2026-08-25  116bee62  codex/workforce-snapshot-iso   failure
2026-08-24  e42616b1  codex/workforce-snapshot-iso   failure
2026-08-23  0b3f6fbb  fix/workforce-generic-role-n   failure

pytest_package on master (push runs) is affected too: green at 473388d3
(run of 2026-08-14), failing at 76da662d and bc07a096 (runs of 2026-08-21),
with 117 collection errors — 116 of them this same FastMCP ImportError. No
camel commit lands between 473388d3 and 76da662d, so the trigger is on the
mcp side.

Reproducible example code

The Python snippets:

# after `pip install -e .` in a clean venv
import importlib.metadata as m
print(m.version("mcp"))          # 2.1.0

import mcp.server as s
print(hasattr(s, "FastMCP"))     # False
print(hasattr(s, "MCPServer"))   # True

import camel.agents               # ImportError

Command lines:

python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest dotenv
pytest test/integration_test/test_minimal_dependency.py -m "not model_backend"

Extra dependencies:

none -- this is the Minimal dependency check job's own command

Steps to reproduce:

1. Clean venv, pip install -e . on unmodified master. mcp resolves to
   2.1.0.
2. Run the job's command above. Result: 3 failed, 4 passed, 1 deselected —
   the three failures are camel.agents, camel.societies and
   camel.societies.workforce, exactly the three the CI job reports.

Traceback

camel/agents/__init__.py:15: in <module>
    from .chat_agent import ChatAgent
camel/agents/chat_agent.py:61: in <module>
    from camel.agents._utils import (
camel/agents/_utils.py:21: in <module>
    from camel.toolkits import FunctionTool
camel/toolkits/__init__.py:24: in <module>
    from .math_toolkit import MathToolkit
camel/toolkits/math_toolkit.py:18: in <module>
    from camel.toolkits.base import BaseToolkit
camel/toolkits/base.py:61: in <module>
    class BaseToolkit(metaclass=AgentOpsMeta):
camel/toolkits/base.py:68: in BaseToolkit
    from mcp.server import FastMCP
E   ImportError: cannot import name 'FastMCP' from 'mcp.server'

Expected behavior

pip install -e . on master should produce an importable camel.agents, and
Minimal dependency check should pass.

Additional context

Two possible fixes, and I want to be explicit that I picked the smaller one:

1. Cap mcp below 2.0.0 — three one-line specifier changes in
   pyproject.toml plus the matching uv.lock entries. This is what fix(deps): cap mcp below 2.0.0, which removed FastMCP #4247
   proposed.
2. Migrate to the mcp 2.x API (mcp.server.MCPServer) — this touches
   camel/toolkits/base.py, camel/utils/mcp.py, MCPToolkit, MCPAgent and
   mcp_client. Note that fix(toolkits): import FastMCP from mcp.server.fastmcp #4238's approach of importing from
   mcp.server.fastmcp cannot work: that module does not exist in 2.x either.

I have (1) ready and measured, in clean Python 3.11 venvs running the job's own
command:

	resolved mcp	result
master	2.1.0	3 failed, 4 passed
with the cap	1.29.1	7 passed

The uv.lock change is only the three specifier records; the locked mcp
version stays at 1.28.1, so nothing else in the lock moves. Capping does not
block (2) later.

Happy to open the PR, or to leave it if you would rather go straight to the 2.x
migration.

[JessYanCoding]

Fixed by #4313, which caps mcp>=1.3.0,<2 in the base, dev_tools and all
dependency sets and updates uv.lock to match — landing on the same reasoning
this issue arrived at, that constraining the dependency is the smallest
compatible fix and a full v2 migration is separate work.

Verified on current master (d1987151): all three specifiers carry the cap,
and uv.lock records them. Closing as resolved. #4294 is closed as superseded.

One thing that may still be worth a look, unrelated to the cap: #4288 carries a
try/except shim in camel/toolkits/base.py that falls back to
FastMCP = Any. With the cap in place it is no longer needed, and on mcp 2.x
both of its import paths fail, so it would resolve to Any and turn the import
error into a missing type plus a later runtime failure at the three call sites
that construct FastMCP directly (camel/utils/mcp.py:221,
camel/agents/chat_agent.py:6424, camel/societies/workforce/workforce.py:5955).
Flagging it here rather than on that PR since @ebarkhordar already raised it
there.