google / google/adk-docs

ADK Docs MCP Server snippets fail on fresh install: mcpdoc is incompatible with mcp 2.x

Open Beginner friendly
#2,219 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
1.5k
Forks
1.3k
Avg merge
7d 1h
Merged PRs (30d)
34

Description

## Summary

The ADK Docs MCP Server snippets in `docs/tutorials/coding-with-ai.md` (Antigravity, Claude Code, Cursor) no longer work on a fresh install. `uvx --from mcpdoc mcpdoc ...` resolves `mcp` 2.x, and `mcpdoc` 0.0.10 still imports `mcp.server.fastmcp.FastMCP`, which was removed in `mcp` 2.0. The server crashes before the MCP handshake, so Claude Code reports `Connection closed` and Cursor/Antigravity show the server as failed.

## Reproduce

```bash
uvx --from mcpdoc mcpdoc --urls AgentDevelopmentKit:https://adk.dev/llms.txt --transport stdio
```

```
File ".../site-packages/mcpdoc/main.py", line 9, in
from mcp.server.fastmcp import FastMCP
ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x, where FastMCP was renamed to MCPServer ... or pin 'mcp<2' to keep running v1 code.
```

Tested 2026-09-10 on macOS with `uvx` 0.11.24. `uvx --refresh` gives the same result, so it is not a stale cache.

## Cause

- `mcpdoc` 0.0.10 (latest on PyPI, July 2025) declares `mcp[cli]>=1.4.1` with no upper bound.
- `mcp` 2.0.0 shipped 2026-07-28 and renamed `FastMCP` to `MCPServer`.
- Upstream tracking issue: langchain-ai/mcpdoc#67 (open).

Because the snippet uses `uvx --from` with no lockfile, every new install since late July resolves the incompatible pair.

## Suggested fix

Add `--with "mcp<2"` to the `uvx` invocation in all three snippets until `mcpdoc` publishes an `mcp` 2.x compatible release. Verified working:

```bash
claude mcp add adk-docs --transport stdio -- uvx --from mcpdoc --with "mcp<2" mcpdoc --urls AgentDevelopmentKit:https://adk.dev/llms.txt --transport stdio
```

and for the JSON configs:

```json
"args": ["--from", "mcpdoc", "--with", "mcp<2", "mcpdoc", "--urls", "AgentDevelopmentKit:https://adk.dev/llms.txt", "--transport", "stdio"]
```

With the pin the server starts and answers `initialize` with `list_doc_sources` and `fetch_docs` advertised.

A short note in that section explaining why the pin is there would help readers who hit the error before the doc is updated.

Contributor guide

Open the contributing guide

Research direction

Open docs/tutorials/coding-with-ai.md and find the Antigravity, Claude Code, and Cursor ADK Docs MCP Server snippets. Reproduce the failure with the provided uvx command, then update each invocation with the mcp<2 constraint and add the brief compatibility note. Done means all three configurations start successfully and complete the MCP initialize handshake.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, shell
Domain
documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.