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

[GigaHierz]

What & why

The Celo MCP Server page described the server as it was several releases ago: local stdio only, a tool list that no longer matched what the server registers, and setup guidance for an entry point that had been renamed. This rewrites the page against the published celo-mcp 0.4.1 wheel on PyPI, which is what pipx install celo-mcp and the uvx client configs on the page actually install. An earlier revision of this PR was written against upstream main ahead of that release; the branch was rewritten once 0.4.1 shipped.

Separate from #2287 (Celina pages), which only cross-links this page and has since merged.

Changes

build-on-celo/build-with-ai/mcp/celo-mcp.mdx

• Intro and "What it covers" state the current read-only surface: blocks, transactions, balances, gas, governance, staking and validators. The NFT, contract-call and transaction-simulation claims are gone because no tool provides them. "Never signs or sends a transaction" is true of the exposed tools.
• RPC note. The server always reads from Celo Mainnet via https://forno.celo.org. The endpoint is not configurable in 0.4.1 and there is no testnet mode; the page says so instead of documenting a CELO_RPC_URL that nothing reads.
• "Connect your client" is a <Tabs> block per client for the local stdio setup, with the celo-mcp entry point and pipx/uvx install paths.
• "Run as a remote HTTP endpoint" covers the celo-mcp-server entry point and Streamable HTTP at /mcp, with a table of the environment variables it honours: MCP_TRANSPORT, HOST/PORT, MCP_ALLOWED_HOSTS, MCP_CORS_ORIGINS, MCP_RATE_LIMIT/MCP_RATE_WINDOW, MCP_TRUST_PROXY, MCP_AUTH_TOKEN, plus the /health route and the 421 you get when the Host header is not allow-listed. Client config for the remote case is a second <Tabs> block.
• "Available tools" is the 15 tools 0.4.1 registers, one to one, grouped by area. Seven tools that upstream dropped are removed (get_account, get_token_info, get_nft_info, get_nft_balance, call_contract_function, estimate_contract_gas, estimate_transaction); six that were missing are added (get_stable_token_balance, get_staking_balances, get_activatable_stakes, get_total_staking_info, get_validator_groups, get_validator_group_details). Pagination parameters are noted where a tool has them.
• Stablecoin symbols. get_celo_balances reads symbol() on chain and returns USDm/EURm/BRLm; get_stable_token_balance uses the server's built-in token table and reports the same three assets as cUSD/cEUR/cREAL. Each bullet says which, and the note tells readers to match on token address when combining the two.
• Development section uses the sdist's src/ layout and ruff (the dev extra), replacing isort/flake8.
• Headings in sentence case; ## Resources and ## Related added per AGENTS.md.

build-on-celo/build-with-ai/mcp/index.mdx: the Celo MCP Server summary bullet now says balances, governance, staking and validators, local or remote.

build-on-celo/build-with-ai/use-docs-with-ai.mdx: the card no longer claims NFT support.

Verification

Against the published wheel, not the repository: celo_mcp-0.4.1-py3-none-any.whl from PyPI.

• entry_points.txt carries celo-mcp and celo-mcp-server; http_app.py ships in the wheel; requires_dist lists starlette and uvicorn. Every run command on the page resolves from pipx install celo-mcp.
• Tool list: fifteen Tool(name=...) registrations in server.py, fifteen on the page, nothing extra either way.
• Env-var table checked variable by variable against http_app.py and server.py:cli, including the defaults.
• RPC note: CeloClient() is constructed with no arguments and the settings object never reaches rpc_url.
• Symbol behaviour: tokens/service.py:186 calls symbol() on chain for get_celo_balances; :508 builds get_stable_token_balance results from the table at :82-96.
• mint broken-links green on the branch head. All internal links resolve, celina included now that docs(build-with-ai): add Celina SDK, MCP, hosted MCP, and API pages #2287 has merged.

[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.

[GigaHierz]

The release landed — this needs a re-read rather than a re-review of what you saw.

You reviewed on 2026-08-28, when PyPI's latest celo-mcp was 0.3.3. 0.4.1 was uploaded 2026-08-31 at 14:35, and the branch was rewritten against it that evening (7ac9513f, "rewrite the Celo MCP page against the released 0.4.1"). Unpacking the published 0.4.1 wheel:

$ unzip -p celo_mcp-0.4.1-*.whl '*.dist-info/entry_points.txt'
[console_scripts]
celo-mcp        = celo_mcp.server:main_sync
celo-mcp-server = celo_mcp.server:cli

$ unzip -l celo_mcp-0.4.1-*.whl | grep http_app
celo_mcp/http_app.py

$ requires_dist
… starlette>=0.37.0 …

So celo-mcp-server, http_app.py and the starlette dependency are all in the released package now. pipx install celo-mcp and the uvx client configs on the page resolve, and the "Connect Remotely" section describes capability that is installable today. That removes the blocker as stated.

Your other points look addressed in the same rewrite — spot-checked against the current head:

• CELO_RPC_URL — took your first option. Line 32 now says outright: "The server always reads from Celo Mainnet at https://forno.celo.org. The RPC endpoint is not configurable in the current release — the client is constructed without arguments, so neither CELO_RPC_URL nor the CELO_MCP_-prefixed settings reach it. There is no testnet mode."
• MCP_TRUST_PROXY — now documented.
• get_validator_groups — pagination noted.
• Headings — sentence case throughout (## What it covers, ## Connect your client, ## Run as a remote HTTP endpoint).
• ## Resources and ## Related — both added.
• The NFT card on use-docs-with-ai.mdx — no NFT occurrences left.
• Per-client config — two <Tabs> blocks.

I have not re-verified the tool list or the MCP_AUTH_TOKEN / HOST / MCP_ALLOWED_HOSTS guidance line by line against 0.4.1, so those are worth your eye rather than my assurance.

Also worth knowing: #2287 merged, and it edited the same list block in mcp/index.mdx you flagged. This branch is 2 behind main but git merge-tree reports no conflict, so that one resolved itself.

CI is green on the current head.

[palango]

Re-verified against the published 0.4.1 wheel rather than upstream main. Downloaded from PyPI, sha256 a1d1ed2d556caa13b673514743bd1d1de9ab56cf3276ab763cd1733c725b118f, matching the hash PyPI reports for the file. The blocker is gone: entry_points.txt carries both celo-mcp and celo-mcp-server, http_app.py ships in the wheel, and requires_dist lists starlette>=0.37.0 and uvicorn>=0.30.0. Every run command on the page works from pipx install celo-mcp.

Both things you left open hold up.

The tool list is an exact 1:1: fifteen Tool(name=...) registrations in server.py, fifteen on the page, nothing extra in either direction. The seven tools the body says upstream dropped are all genuinely absent from 0.4.1.

The HTTP guidance matches http_app.py and server.py:cli variable by variable: MCP_TRANSPORT, HOST/PORT at 127.0.0.1/3000, MCP_ALLOWED_HOSTS, MCP_CORS_ORIGINS defaulting to *, MCP_RATE_LIMIT/MCP_RATE_WINDOW at 60/60 with /health exempt, MCP_TRUST_PROXY as a hop count, MCP_AUTH_TOKEN as bearer with /health left open. The /mcp path matches streamable_http_path. The 421 is real: mcp/server/transport_security.py returns Response("Invalid Host header", status_code=421), and because _transport_security() defaults allowed_hosts to the bind host, --host 0.0.0.0 does produce connection-refused first and 421 second, in that order. Setting MCP_ALLOWED_HOSTS to a bare public hostname matches by exact comparison, so the fix the page gives is the one that works.

One thing left, and it is the first round's failure mode in a new place. The note at lines 118-120 tells the reader these tools return USDm, EURm and BRLm. That holds for get_celo_balances, which resolves symbols on chain through get_token_balance → get_token_info → contract.functions.symbol(). I checked the three contracts against forno and they answer USDm, EURm, BRLm. It does not hold for get_stable_token_balance. That one never calls symbol(); it multicalls balanceOf and builds each result from the hardcoded table:

# tokens/service.py:507
token_symbol=token_info["symbol"],   # "cUSD" / "cEUR" / "cREAL"

So the two tools report different symbols for the same three assets, and the note sits under both bullets. An agent reading this page as tool documentation will look for USDm in get_stable_token_balance output and read the balance as missing. A clause on line 114 saying that tool reports the registry symbols cUSD/cEUR/cREAL closes it.

The rest:

• Requires-Python: >=3.11 matches the prerequisite, and the sdist's src/ layout makes black src/, ruff check src/ and mypy src/ correct. ruff is in the dev extras.
• docs/DEPLOYMENT.md exists on main and returns 200. All four internal links resolve on the branch, celina included now that docs(build-with-ai): add Celina SDK, MCP, hosted MCP, and API pages #2287 has merged.
• Headings are sentence case, and no deleted heading was an anchor target. Nothing in the repo links to celo-mcp#, and the only redirect involved, /build/mcp/celo-mcp, carries no fragment.
• The RPC note is precise. service.py:15 constructs CeloClient() with no arguments, self.settings is loaded and never reaches self.rpc_url, and the sdist's .env.example is empty, so nothing upstream contradicts the page.
• "Never signs or sends a transaction" is true of the exposed surface. sign_transaction and send_raw_transaction do exist in transactions/service.py, but no tool routes to them and none takes a key.

Two optional ones, not defects: get_governance_proposals is called paginated without its default of 10 where get_validator_groups gives its default, so the asymmetry now runs the other way from my first comment; and get_latest_blocks omits its offset parameter.

Separately, the body has not kept up with the branch. It still says the commands were verified against the current celo-org/celo-mcp main, which is the wording that produced the blocker, never mentions 0.4.1, and describes none of the rewrite: no RPC note, no remote client tabs, no Resources or Related. It also carries a Claude Code footer.

Fix line 114 and rewrite the body and I will approve.

[GigaHierz]

Both done in cf9b5d70, as a plain commit on top.

Line 114. Each balance bullet now says where its symbols come from: get_celo_balances reads symbol() on chain and returns USDm/EURm/BRLm; get_stable_token_balance uses the server's built-in token table and reports the same three as cUSD/cEUR/cREAL. The note under them now says the two tools name the same assets differently and to match on token_address when combining output, which every TokenBalance carries. Verified against the 0.4.1 wheel the same way you did: tokens/service.py:186 is the on-chain symbol() call on the get_celo_balances path, :508 is token_symbol=token_info["symbol"] from the table at :82-96.

The two optional ones, taken since both are one clause and checkable in server.py's inputSchema: get_latest_blocks now names count (default 10, max 100) and offset; get_governance_proposals names page_size (default 10, max 20).

The body is rewritten against the branch as it is: verified against the published 0.4.1 wheel rather than upstream main, and it now describes the RPC note, the remote client tabs, the env-var table, ## Resources and ## Related, the 15-tool list, and the symbol clarification. Footer gone.

mint broken-links green on the new head. Re-requesting you.