Fix MCP Python SDK 2.0 McpError ImportError

If uvx mcp-server-fetch or uvx mcp-server-time now exits with ImportError: cannot import name 'McpError', run the server with MCP Python SDK 1.x while its package is being migrated:

uvx --with "mcp<2" mcp-server-fetch

For the time server, use the same constraint:

uvx --with "mcp<2" mcp-server-time

MCP Python SDK 2.0.0 renamed McpError to MCPError, but the affected reference servers declared an open-ended mcp dependency. A fresh unpinned resolution can therefore combine v1 server code with the v2 SDK. Pinning mcp<2 restores the compatible dependency line without changing credentials or client configuration.

Do not fix a dependency mismatch by editing files inside the temporary uvx environment. Do not assume that replacing one class name completes a v2 migration. The SDK also changed the exception constructor, low-level handler registration, transports, types, and other APIs.

Confirm This Is the Same Failure

This guide applies when the traceback contains all of these signals:

• the failing package is a Python MCP server such as mcp-server-fetch or mcp-server-time;

• the process exits during import, before the MCP connection starts;

• the traceback points to mcp.shared.exceptions;

• Python says McpError cannot be imported and may suggest MCPError;

• the environment resolved mcp==2.0.0 or another 2.x release.

The important line looks like this:

ImportError: cannot import name 'McpError' from 'mcp.shared.exceptions'. Did you mean: 'MCPError'

If the server starts and the client later reports a timeout, authorization error, protocol-version mismatch, or connection refusal, diagnose that separate boundary. Aident's MCP server connection guide covers startup and transport failures that do not match this import error.

Prerequisites

Before changing dependencies:

• preserve the complete traceback and the command that launched the server;

• identify whether you use uvx, a project managed by uv, or a virtual environment managed by pip;

• save the current lockfile if the server is part of your own project;

• avoid deleting client configuration or authentication files;

• use a test branch for a full SDK v2 migration.

Step 1: Check the Resolved MCP Version

For a uv project, run:

uv run python -c "from importlib.metadata import version; print(version('mcp'))"

For an activated virtual environment, run:

python -c "from importlib.metadata import version; print(version('mcp'))"

Expected result: 2.0.0 confirms the new SDK is present. The version alone is not proof of a bug in your server, but the version plus the exact McpError traceback identifies the v1/v2 mismatch.

If you launch the published reference server only through uvx, skip permanent project changes and test the bounded command in Step 2.

Step 2: Run the Published Server With MCP 1.x

Run the affected package with an explicit upper bound:

uvx --with "mcp<2" mcp-server-fetch

or:

uvx --with "mcp<2" mcp-server-time

Expected result: the process no longer exits on the McpError import. In an MCP client, the server should remain available long enough to complete its normal v1 initialization.

This is a compatibility pin, not a permanent SDK upgrade. Keep it in the client command or package configuration until the server publishes a release that supports v2. Remove it only after verifying that release against the v2 migration notes.

If the same traceback still names SDK 2.x, inspect the exact command the client runs. A wrapper, another binary on PATH, or a second configuration entry may still be launching the unbounded command.

Step 3: Pin an Existing v1 Project Deliberately

If the failing server is part of your project and you are not ready to migrate it, set a v1 upper bound in the project's dependency source of truth.

With uv:

uv add "mcp<2"
uv run python -m pip check
uv run python -c "from importlib.metadata import version; print(version('mcp'))"

With pip in an activated virtual environment:

python -m pip install "mcp<2"
python -m pip check
python -c "from importlib.metadata import version; print(version('mcp'))"

Expected result: the resolver selects a 1.x version, dependency checks pass, and the original server imports again. Commit the dependency declaration and lockfile together so another machine does not silently resolve SDK 2.x.

Do not copy McpError or another class into your project. The package constraint is the smallest reversible repair because it restores the API line the server was written against.

Step 4: Verify Startup Before Testing Tools

Test the server outside your main client first:

uvx --with "mcp<2" mcp-server-fetch

Expected result: no import traceback appears. A stdio server may wait quietly for a client; that is normal.

Then test the same command with MCP Inspector. Verify these boundaries in order:

1. the process starts;

2. initialization completes;

3. the tool list appears;

4. one harmless read-only call returns a result;

5. stderr contains no hidden dependency traceback.

Testing startup before a tool call keeps an import failure separate from DNS, proxy, authorization, and provider errors.

Step 5: Migrate to SDK 2 as One Coherent Change

SDK 2 is a major migration, not a spelling patch. The official migration guide lists changes that commonly travel with the McpError rename, including:

• McpError becoming MCPError with a different constructor;

• FastMCP becoming MCPServer;

• low-level decorators becoming constructor callbacks;

• Python field names changing from camel case to snake case;

• transport and HTTP client changes;

• removed or renamed types and deprecated protocol features.

For maintained server code, create a migration branch and follow this order:

1. change the dependency range to the reviewed 2.x line;

2. apply the official import and type migrations;

3. port the high-level or low-level server API as one unit;

4. update transport and authorization wiring;

5. run unit tests and protocol tests;

6. test a clean install with no old lockfile;

7. roll out with a documented rollback to the last v1-compatible release.

Aident's MCP 2026-07-28 migration checklist covers the protocol-level rollout. The SDK migration guide remains the source of truth for Python API changes.

Common Failure Modes

Why the Pin Works

The published server and the SDK are separate packages. An open-ended dependency such as mcp>=1.23 permits a resolver to choose 2.0.0 even when the server source still uses v1 APIs. mcp<2 adds the missing compatibility boundary, so the resolver selects the newest allowed 1.x SDK instead.

That restores the contract the server already expects. It does not make v1 code support the 2026-07-28 protocol or remove the need for a future migration. The distinction matters: a safe short-term recovery constrains dependency resolution, while a durable upgrade changes and tests the whole affected API surface.

Verify One Connected Action With Aident Loadout

After the server starts, verify an unrelated connected Action without placing a provider credential in the MCP configuration. Install or update Aident Loadout with this prompt:

Follow https://aident.ai/SETUP.md

Then run:

aident account auth status
aident vault vault --action status
aident capabilities search \
  --queries '["find a connected read-only GitHub Action that searches issues"]' \
  --types '["action"]'

Inspect the selected contract before execution:

aident capabilities get --name "<canonical-action-name>"

Success means one current Action schema is available through the managed integration boundary, with no provider secret copied into the repaired server. This does not change the server's Python dependency; it verifies that your agent can still discover a connected capability after the local runtime repair.

Use Aident Loadout to inspect one read-only Action. Measure success as one live schema inspected, zero provider secrets pasted, and zero repository changes.

Sources

• MCP Python SDK v1 to v2 migration guide, Model Context Protocol, accessed July 29, 2026

• MCP Python SDK repository, Model Context Protocol, accessed July 29, 2026

• MCP 2026-07-28 specification release, Model Context Protocol, published July 28, 2026

• mcp-server-time SDK 2.0 McpError ImportError, Model Context Protocol servers issue, opened July 29, 2026

• mcp-server-fetch SDK 2.0 McpError ImportError, Model Context Protocol servers issue, opened July 28, 2026

• mcp-server-fetch SDK v2 migration, Model Context Protocol servers pull request, opened July 28, 2026

• Aident setup instructions, accessed July 29, 2026

Refresh this guide when the affected reference servers publish SDK 2-compatible releases, the Python SDK changes its v1 maintenance policy, or the official migration steps change.