docs(mcp): refresh Celo MCP Server page for remote HTTP transport and current tool set

[GigaHierz]

What & why

The Celo MCP Server page had drifted from the upstream celo-org/celo-mcp repo. Two upstream changes in particular were not reflected in the docs:

• Remote MCP support — the server now runs as a remote endpoint over Streamable HTTP (single URL, no local Python install). The page documented only the local stdio setup.
• mcp 2.x migration — the entry point changed and the tool set was reworked.

This is a separate change from #2287 (which adds the third-party Celina pages and only cross-links this page).

Changes

• Remote transport: new "Connect Remotely (Streamable HTTP)" section — HTTP run commands, URL-based client config, and the env-var configuration table (MCP_TRANSPORT, HOST/PORT, MCP_ALLOWED_HOSTS, MCP_CORS_ORIGINS, rate limiting, MCP_AUTH_TOKEN) plus the /health note.
• Available Tools reconciled to the server's actual 15 tools:
  • Removed tools no longer registered upstream: get_account, get_token_info, get_nft_info, get_nft_balance, call_contract_function, estimate_contract_gas, estimate_transaction.
  • Added missing tools: get_stable_token_balance, get_staking_balances, get_activatable_stakes, get_total_staking_info, get_validator_groups, get_validator_group_details.
• Key Features & intro corrected to the current read-only capabilities (removed NFT / smart-contract / transaction-simulation claims that no longer apply).
• Run command updated to celo-mcp-server; Code Quality section updated to ruff (was isort/flake8).
• MCP index page: refreshed the Celo MCP Server summary bullet (balances, staking/validators, local-or-remote).

Verification

• Tool names, transport flags, and env-var table verified against the current celo-org/celo-mcp main (src/celo_mcp/server.py, pyproject.toml, README.md).
• mint broken-links passes on this branch head.

🤖 Generated with Claude Code

[palango]

The reconciliation itself checks out: I verified the 15-tool list against upstream server.py, the env-var names and defaults against http_app.py, and the deleted heading anchors have no inbound links. But there's a blocker: the page now documents code that isn't released.

The PR body says the commands were verified against main, and that's the problem. PyPI's latest celo-mcp is 0.3.3 (uploaded 2026-08-17). Its wheel declares a single entry point, celo-mcp = celo_mcp.server:main_sync. No celo-mcp-server, no http_app.py, no --transport flag, no starlette/uvicorn dependencies. And pyproject.toml on main still says 0.3.3, so no release with the new code appears queued. Anyone who follows the page's own install step (pipx install celo-mcp, or the uvx client configs) gets command-not-found from every run command on the page (lines 123, 125, 211, 214), and the PR removed the python -m celo_mcp.server invocation that does work with the released package. The whole "Connect Remotely" section and the new index bullet describe capability nobody can install today. I'd either hold this until upstream cuts a release, or keep the released stdio command and mark the new content as requiring a checkout (e.g. uvx --from git+https://github.com/celo-org/celo-mcp celo-mcp-server).

Worth fixing in the same pass:

• CELO_RPC_URL / CELO_TESTNET_RPC_URL (line 47): nothing reads these. Settings use the CELO_MCP_ env prefix, and even that binding is dead, because CeloClient.__init__ hardcodes https://forno.celo.org (the testnet branch hardcodes Alfajores, whose host no longer resolves). Exporting the documented variables silently leaves you on mainnet forno. Either drop the section or say the endpoint is currently not configurable.
• The remote client config (lines 130-136) fails silently in Claude Code, which treats a bare url without "type": "http" as stdio and skips it, and VS Code wants a servers key, not mcpServers. use-docs-with-ai.mdx:63-76 warns about exactly this, so the two pages now disagree. Per-client <Tabs> (AGENTS.md:102) would fix it.
• The card on use-docs-with-ai.mdx:214 still advertises NFTs and doesn't mention staking. That's the third copy of the capability list; this PR updated the other two.
• get_validator_groups (line 179) is paginated (default page_size 10, max 50), not "all validator groups". Since the page documents pagination for get_governance_proposals two bullets up, the omission reads as "not paginated", and an LLM using this page as tool documentation will report the first 10 groups as the full set.
• get_celo_balances and get_stable_token_balance (lines 163-164) read as duplicates. The actual difference: the first covers CELO plus cUSD/cEUR/cREAL, the second multicalls the wider token registry (USDT, USDC, USDGLO, cKES and more). The deleted USDm/EURm/BRLm note was also the only place the page explained the symbols these tools return.
• Three gaps in the HTTP section: the env table is missing MCP_TRUST_PROXY (without it, rate limiting behind Cloud Run or any load balancer keys on the proxy IP and all clients share one 60/min bucket); MCP_AUTH_TOKEN has no client-side example showing the bearer header, so the only lockdown knob has no client half; and the quickstart binds 127.0.0.1 with localhost-only allowed hosts, so a remote client fails first with connection refused and then with HTTP 421, and nothing on the page maps those symptoms to HOST / MCP_ALLOWED_HOSTS.

Smaller:

• The four new headings are Title Case; AGENTS.md:71 asks for sentence case on new or rewritten headings. Fixing it later re-slugifies the anchors a second time.
• The remote section sits under "MCP Client Integration" but is mostly server operation, and the run command now appears three times (123, 125, 214). Give it one home: its own H2 next to "Running the Server", or folded into it. Also "The stdio setup above is unchanged; this is an additional transport" is changelog voice; docs readers don't have a prior version to compare against.
• The page has no ## Related / ## Resources and zero internal links (AGENTS.md:149). A Resources link to celo-org/celo-mcp would also give the hand-copied tool list an authoritative anchor against future drift.
• Heads-up: docs(build-with-ai): add Celina SDK, MCP, hosted MCP, and API pages #2287 edits the same list block in mcp/index.mdx, so whichever merges second will conflict.
• Pre-existing, but since you're on this page: the VS Code section (line 59) points macOS/Linux users at ~/.vscode/mcp.json, which VS Code doesn't read, and uses mcpServers where VS Code wants servers.

[GigaHierz]

Reproduced the release blocker independently before touching anything — you are right, and the page cannot ship as written.

$ curl -s https://pypi.org/pypi/celo-mcp/json | jq -r .info.version
0.3.3                                  # uploaded 2026-08-17

$ pip download celo-mcp==0.3.3 --no-deps && unzip -p celo_mcp-0.3.3-py3-none-any.whl \
    "*.dist-info/entry_points.txt"
[console_scripts]
celo-mcp = celo_mcp.server:main_sync   # the only entry point

$ unzip -l celo_mcp-0.3.3-py3-none-any.whl | grep -c http_app
0

requires_dist for 0.3.3 lists no starlette and no uvicorn, so even a source install of the released version cannot serve HTTP. Every celo-mcp-server invocation on the page is command-not-found for anyone following the page's own install step, and the PR removed the python -m celo_mcp.server form that does work.

I have not rewritten the page, because the fix depends on a call that is not mine to make:

1. Hold until upstream cuts a release, or
2. Ship now with the released stdio command as the documented path and the remote/HTTP section explicitly marked as requiring a checkout (uvx --from git+https://github.com/celo-org/celo-mcp celo-mcp-server).

I would rather not guess between "documentation for unreleased software, labelled" and "wait" on a page whose job is install instructions. @GigaHierz — which one?

The rest of your list is unambiguous and I will apply it in whichever direction is chosen. Flagging two that change what gets written rather than just how:

• CELO_RPC_URL / CELO_TESTNET_RPC_URL: confirmed nothing reads them, and the testnet branch hardcodes an Alfajores host that no longer resolves. That is a live wrong-config trap, so the section should say the endpoint is not configurable rather than be quietly deleted.
• get_validator_groups pagination: agreed this is the worst of the tool-list errors, precisely because an LLM reading the page as tool documentation will report the first 10 groups as the complete set.

Also noting your conflict warning: #2287 touches the same list block in mcp/index.mdx.

[GigaHierz]

Unblocked — 0.4.1 is on PyPI and the page is rewritten against the published wheel, not upstream main. 34dcd645.

$ curl -s https://pypi.org/pypi/celo-mcp/json | jq -r .info.version
0.4.1                                    # uploaded 2026-08-31T14:35

$ pip download celo-mcp==0.4.1 --no-deps && unzip -p celo_mcp-0.4.1-py3-none-any.whl "*.dist-info/entry_points.txt"
[console_scripts]
celo-mcp = celo_mcp.server:main_sync
celo-mcp-server = celo_mcp.server:cli   # present now

$ unzip -l celo_mcp-0.4.1-py3-none-any.whl | grep -c http_app
1
$ ... requires_dist | grep -E "starlette|uvicorn"
starlette>=0.37.0, uvicorn>=0.30.0

Every run command on the page now works from pipx install celo-mcp.

On the RPC variables — you were right, and it is worse than "nothing reads these". I traced it rather than just deleting the section:

config/settings.py      env_prefix = "CELO_MCP_"      # so CELO_RPC_URL is dead
blockchain_data/service.py:15   self.client = client or CeloClient()   # no arguments
blockchain_data/client.py:33-38 if rpc_url: ... else: "https://forno.celo.org"

So CELO_MCP_RPC_URL is dead too — the setting is loaded into self.settings and never reaches self.rpc_url. The endpoint is not configurable at all, and there is no testnet mode. The page now says exactly that in a Note. (The Alfajores default at line 36 is unreachable through this path, which is lucky: that host fails to connect.)

Tool list. Diffed rather than re-read:

$ grep -oE 'name="[a-z_]+"' celo_mcp/server.py | sort -u | wc -l
15

Exact match with the page. This also settles your card point: celo_mcp/nfts/ exists as a module but registers no tools, so the "NFTs" claim on use-docs-with-ai.mdx was wrong rather than merely stale. Fixed.

The rest as you listed: get_validator_groups pagination called out explicitly (page_size defaults to 10), the two balance tools differentiated with the USDm/EURm/BRLm note restored, "type": "http" and VS Code's servers key in per-client tabs, the ~/.vscode/mcp.json path corrected, MCP_TRUST_PROXY documented with the shared-bucket consequence, a bearer-header example for MCP_AUTH_TOKEN, and a Warning mapping connection-refused → HOST and HTTP 421 → MCP_ALLOWED_HOSTS.

Structure: remote is its own H2 (it is server operation, not client integration), the run command appears once instead of three times, headings are sentence case, the changelog aside is gone, and the page has Resources and Related — it had no internal links at all before.

Rebased on main, so the #2287 conflict in mcp/index.mdx is resolved. broken-links green. The orphan check reports 20, all of them #2293's and unrelated to this branch.