ADK Docs MCP Server snippets fail on fresh install: mcpdoc is incompatible with mcp 2.x
- 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
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