From 09e253fd68a464f96fd46bee73d87e772ca73e5a Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Wed, 26 Aug 2026 13:49:42 +0100 Subject: [PATCH 1/4] docs(mcp): refresh Celo MCP Server page for remote HTTP transport and current tool set Reconcile the Celo MCP Server page with the upstream celo-org/celo-mcp repository, which has drifted from the docs: - Document the remote Streamable HTTP transport (added upstream), including the HTTP run commands, URL-based client config, and env-var configuration table (MCP_TRANSPORT, HOST/PORT, MCP_ALLOWED_HOSTS, auth token, etc.). - Replace the Available Tools list with the server's actual 15 tools: drop tools no longer registered (get_account, get_token_info, both NFT tools, both contract tools, estimate_transaction) and add the missing balances/staking/validator tools (get_stable_token_balance, get_staking_balances, get_activatable_stakes, get_total_staking_info, get_validator_groups, get_validator_group_details). - Correct Key Features and the intro to match read-only capabilities (remove NFT/smart-contract/simulation claims that no longer apply). - Update the run command to the current entry point (celo-mcp-server) and the Code Quality section to ruff (replacing isort/flake8). - Refresh the summary bullet on the MCP index page. Co-Authored-By: Claude Opus 4.8 --- build-on-celo/build-with-ai/mcp/celo-mcp.mdx | 109 +++++++++++-------- build-on-celo/build-with-ai/mcp/index.mdx | 6 +- 2 files changed, 65 insertions(+), 50 deletions(-) diff --git a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx index 1d9dff899..eb16e299a 100644 --- a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx +++ b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx @@ -1,18 +1,18 @@ --- title: Celo MCP Server -description: Connect AI assistants to Celo blockchain data, tokens, contracts, and governance through the Celo MCP server +description: Connect AI assistants to Celo blockchain data, balances, governance, and staking through the Celo MCP server --- -The **Celo MCP Server** is a Model Context Protocol (MCP) server that provides comprehensive access to the Celo blockchain. This powerful tool enables AI assistants and development environments to interact directly with Celo blockchain data, execute token operations, manage NFTs, handle smart contract interactions, process transactions, and participate in governance operations. +The **Celo MCP Server** is a Model Context Protocol (MCP) server that gives AI assistants and development environments read access to the Celo blockchain — blocks, transactions, token balances, gas fees, governance proposals, staking, and validator data. It runs locally over stdio or remotely over Streamable HTTP. ## Key Features -- 🔗 **Blockchain Data Access**: Real-time access to blocks, transactions, and account information -- 💰 **Token Operations**: Complete ERC20 and Mento stable token support (USDm, EURm, BRLm) -- 🖼️ **NFT Management**: Support for ERC721 and ERC1155 standards with metadata fetching -- 📄 **Smart Contract Interactions**: Call functions, estimate gas, and manage ABIs -- 📊 **Transaction Handling**: Gas estimation, EIP-1559 support, and transaction simulation -- 🏛️ **Governance Operations**: Access to Celo governance proposals and voting data +- 🔗 **Blockchain Data Access**: Real-time access to network status, blocks, and transactions +- 💰 **Balances**: CELO, ERC20, and Mento stable token balances for any address +- ⛽ **Gas & Fees**: Current EIP-1559 gas fee data +- 🏛️ **Governance**: Browse Celo governance proposals and read proposal details +- 🥩 **Staking & Validators**: Staking balances, activatable stakes, validator groups, and network-wide staking metrics +- 🌐 **Local or Remote**: Run over stdio (local) or Streamable HTTP (single-URL remote endpoint) ## Prerequisites @@ -113,56 +113,71 @@ For Claude Desktop, add this configuration to your MCP settings file: } ``` -## Available Tools - -### Blockchain Data Operations - -#### Network and Block Information - -- **`get_network_status`**: Get current network status and connection information -- **`get_block`**: Fetch block information by number, hash, or "latest" -- **`get_latest_blocks`**: Get information about recent blocks (up to 100) +### Connect Remotely (Streamable HTTP) -#### Account and Transaction Data +The server can also run as a remote MCP endpoint over Streamable HTTP, so clients connect with a single URL — no local Python install required. The stdio setup above is unchanged; this is an additional transport. -- **`get_account`**: Get account information including balance and nonce -- **`get_transaction`**: Get detailed transaction information by hash +Run it in HTTP mode: -### Token Operations +```bash +celo-mcp-server --transport http --port 3000 +# or via env: +MCP_TRANSPORT=http PORT=3000 celo-mcp-server +``` -#### Token Information and Balances +Then point any remote-capable MCP client at the URL: -- **`get_token_info`**: Get detailed token information (name, symbol, decimals, supply) -- **`get_token_balance`**: Get token balance for a specific address -- **`get_celo_balances`**: Get CELO and stable token balances for an address +```json +{ + "mcpServers": { + "celo": { "url": "https:///mcp" } + } +} +``` -### NFT Operations +The HTTP transport is configured through environment variables: -#### NFT Management +| Variable | Purpose | Default | +| --- | --- | --- | +| `MCP_TRANSPORT` | `stdio` or `http` | `stdio` | +| `HOST` / `PORT` | HTTP bind host / port | `127.0.0.1` / `3000` | +| `MCP_ALLOWED_HOSTS` | Hostnames accepted by the SDK's DNS-rebinding check (comma-separated). Set to your public hostname(s), or `*` to disable | localhost only | +| `MCP_CORS_ORIGINS` | Comma-separated allowed origins (or `*`) | `*` | +| `MCP_RATE_LIMIT` / `MCP_RATE_WINDOW` | Requests per client per window (seconds); `/health` is exempt | `60` / `60` | +| `MCP_AUTH_TOKEN` | If set, requires `Authorization: Bearer ` on `/mcp` | unset (open) | -- **`get_nft_info`**: Get NFT information including metadata and collection details -- **`get_nft_balance`**: Get NFT balance for an address (supports ERC721 and ERC1155) +`GET /health` returns `200` for hosting health checks. See the [repository's deployment guide](https://github.com/celo-org/celo-mcp/blob/main/docs/DEPLOYMENT.md) for container and hosting instructions. -### Smart Contract Operations +## Available Tools -#### Contract Interactions +The server exposes read-only access to on-chain data. All tools are queries — the server does not sign or send transactions. -- **`call_contract_function`**: Call read-only contract functions -- **`estimate_contract_gas`**: Estimate gas for contract function calls +### Network and Blocks -### Transaction Operations +- **`get_network_status`**: Get current network status and connection information +- **`get_block`**: Fetch block information by number, hash, or "latest" +- **`get_latest_blocks`**: Get information about recent blocks (up to 100) +- **`get_transaction`**: Get detailed transaction information by hash -#### Transaction Management +### Balances and Fees -- **`estimate_transaction`**: Estimate gas and cost for transactions +- **`get_celo_balances`**: Get CELO and stable token balances for an address +- **`get_stable_token_balance`**: Get balances of all major stable tokens and CELO for an address (multicall) +- **`get_token_balance`**: Get the balance of a specific token for an address - **`get_gas_fee_data`**: Get current gas fee data including EIP-1559 fees -### Governance Operations - -#### Celo Governance +### Governance - **`get_governance_proposals`**: Get Celo governance proposals with pagination -- **`get_proposal_details`**: Get detailed information about specific governance proposals +- **`get_proposal_details`**: Get detailed information about a specific governance proposal + +### Staking and Validators + +- **`get_staking_balances`**: Get staking balances for an address, broken down by validator group +- **`get_activatable_stakes`**: Get pending stakes that can be activated for rewards +- **`get_total_staking_info`**: Get network-wide staking information and participation metrics +- **`get_validator_groups`**: Get information about all validator groups (members, votes, capacity, performance) +- **`get_validator_group_details`**: Get detailed information about a specific validator group ## Development @@ -174,9 +189,6 @@ pip install -e ".[dev]" # Run tests pytest - -# Run with coverage -pytest --cov=celo_mcp ``` ### Code Quality @@ -184,10 +196,9 @@ pytest --cov=celo_mcp ```bash # Format code black src/ -isort src/ -# Lint code -flake8 src/ +# Lint and type-check +ruff check src/ mypy src/ ``` @@ -196,7 +207,9 @@ mypy src/ Start the MCP server directly: ```bash -# Run the MCP server -python -m celo_mcp.server +# Run the MCP server (stdio transport) +celo-mcp-server +# Or run it as a remote HTTP endpoint +celo-mcp-server --transport http --port 3000 ``` diff --git a/build-on-celo/build-with-ai/mcp/index.mdx b/build-on-celo/build-with-ai/mcp/index.mdx index a324d9143..46f227241 100644 --- a/build-on-celo/build-with-ai/mcp/index.mdx +++ b/build-on-celo/build-with-ai/mcp/index.mdx @@ -8,8 +8,10 @@ description: Learn about the Model Context Protocol and how to use Celo-specific ## Celo specific MCPs: - [Celo MCP Server](/build-on-celo/build-with-ai/mcp/celo-mcp) - - Chain Info - - Governance Proposals + - Chain info, balances, gas fees + - Governance proposals + - Staking and validators + - Runs locally (stdio) or as a remote HTTP endpoint - [Celo Docs MCP Server](/build-on-celo/build-with-ai/use-docs-with-ai) - Search the documentation from your editor - [Celina](/build-on-celo/build-with-ai/mcp/celina) From 5de31a345cf134aac786775cf1466b61425d19ba Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Thu, 27 Aug 2026 20:13:16 +0100 Subject: [PATCH 2/4] docs(mcp): use consistent celo-mcp server key in the remote example Match the four local examples so readers see one server key throughout. Co-Authored-By: Claude Opus 4.8 --- build-on-celo/build-with-ai/mcp/celo-mcp.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx index eb16e299a..c22686842 100644 --- a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx +++ b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx @@ -130,7 +130,7 @@ Then point any remote-capable MCP client at the URL: ```json { "mcpServers": { - "celo": { "url": "https:///mcp" } + "celo-mcp": { "url": "https:///mcp" } } } ``` From 7ac9513f114709031d13ff4bf120d714f7d3fc8c Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Mon, 31 Aug 2026 20:55:33 +0100 Subject: [PATCH 3/4] docs(mcp): rewrite the Celo MCP page against the released 0.4.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit celo-mcp 0.4.1 is on PyPI (2026-08-31) with the `celo-mcp-server` entry point and starlette/uvicorn, so the HTTP transport this page documents is now installable. Verified against the published wheel rather than upstream main. Corrections, each checked against 0.4.1: - The RPC endpoint is not configurable. `CELO_RPC_URL` and `CELO_TESTNET_RPC_URL` are read by nothing; settings use a `CELO_MCP_` prefix, and even those never arrive, because BlockchainDataService constructs `CeloClient()` with no arguments. The server always uses forno mainnet. The page said the opposite and offered a testnet variable whose Alfajores default no longer resolves. - `get_validator_groups` is paginated with `page_size` defaulting to 10. Read as "all validator groups", an assistant using this page as tool documentation reports the first 10 as the complete set. - `get_celo_balances` and `get_stable_token_balance` read as duplicates. The first covers CELO plus the core Mento stablecoins; the second multicalls the wider registry. The USDm/EURm/BRLm note is back, since this page is where the symbols first appear. - The remote client config omitted `"type": "http"`, which Claude Code reads as a stdio server and skips, and used `mcpServers` for VS Code, which wants `servers`. Both are now per-client tabs, matching use-docs-with-ai. - The VS Code stdio section pointed at `~/.vscode/mcp.json`, which VS Code does not read. - `MCP_TRUST_PROXY` was missing. Without it, rate limiting behind a load balancer keys on the proxy IP and every client shares one bucket. - `MCP_AUTH_TOKEN` had no client half; the bearer header is now shown. - The quickstart bound 127.0.0.1 with localhost-only allowed hosts, so a remote client hits connection refused and then HTTP 421 with nothing mapping those symptoms to HOST and MCP_ALLOWED_HOSTS. Now a Warning that names both. - The NFT claim on the use-docs-with-ai card was wrong: the server registers 15 tools and none of them are NFT tools, despite the module existing. Structure: the remote section is server operation, so it is its own H2 rather than a subsection of client integration, and the run command appears once instead of three times. Headings are sentence case, the changelog aside is gone, and the page gains Resources and Related sections — it previously had no internal links at all. Verified: mintlify broken-links green. Tool list diffed against `grep -oE 'name="[a-z_]+"' celo_mcp/server.py` in the 0.4.1 wheel: 15, exact match. Co-Authored-By: Claude Opus 5 (1M context) --- build-on-celo/build-with-ai/mcp/celo-mcp.mdx | 336 ++++++++++-------- .../build-with-ai/use-docs-with-ai.mdx | 2 +- 2 files changed, 182 insertions(+), 156 deletions(-) diff --git a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx index c22686842..635caf99a 100644 --- a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx +++ b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx @@ -3,213 +3,239 @@ title: Celo MCP Server description: Connect AI assistants to Celo blockchain data, balances, governance, and staking through the Celo MCP server --- -The **Celo MCP Server** is a Model Context Protocol (MCP) server that gives AI assistants and development environments read access to the Celo blockchain — blocks, transactions, token balances, gas fees, governance proposals, staking, and validator data. It runs locally over stdio or remotely over Streamable HTTP. +The **Celo MCP Server** gives AI assistants and editors read access to Celo — blocks, transactions, token balances, gas fees, governance proposals, staking and validator data. It runs locally over stdio, or as a remote endpoint over Streamable HTTP. -## Key Features +Every tool is a query. The server never signs or sends a transaction, so it cannot move funds. To give an agent a wallet, see [Celina](/build-on-celo/build-with-ai/mcp/celina). -- 🔗 **Blockchain Data Access**: Real-time access to network status, blocks, and transactions -- 💰 **Balances**: CELO, ERC20, and Mento stable token balances for any address -- ⛽ **Gas & Fees**: Current EIP-1559 gas fee data -- 🏛️ **Governance**: Browse Celo governance proposals and read proposal details -- 🥩 **Staking & Validators**: Staking balances, activatable stakes, validator groups, and network-wide staking metrics -- 🌐 **Local or Remote**: Run over stdio (local) or Streamable HTTP (single-URL remote endpoint) +## What it covers + +- Network status, blocks and transactions +- CELO, ERC-20 and Mento stablecoin balances for any address +- EIP-1559 gas fee data +- Governance proposals and proposal details +- Staking balances, activatable stakes, validator groups and network-wide staking metrics ## Prerequisites - Python 3.11 or higher -- Git (v2.38 or higher) -- An IDE that supports MCP (Cursor or Claude Desktop) - -## Installation - -### Method 1: Direct Installation - -Clone the repository and install dependencies: - -```bash -git clone https://github.com/celo-org/celo-mcp -cd celo-mcp -pip install -e . -``` +- An MCP-capable client — VS Code, Cursor, Claude Desktop, Claude Code, Windsurf or a JetBrains IDE -### Method 2: Using pipx (Recommended) +## Install ```bash -pip install pipx pipx install celo-mcp ``` -## Configuration - -Set up optional environment variables for custom RPC endpoints: - -```bash -export CELO_RPC_URL="https://forno.celo.org" # Default: Celo mainnet -export CELO_TESTNET_RPC_URL="https://forno.celo-sepolia.celo-testnet.org/" # Celo Sepolia testnet -``` - -## MCP Client Integration - -MCP is supported by a wide range of IDEs and development tools. Below are setup instructions for popular options: +`uvx celo-mcp` also works and needs no install step; the client configurations below use it. -### VS Code Setup + +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. + -VS Code has native MCP support. Add the following configuration to your MCP settings: +## Connect your client -**macOS/Linux**: `~/.vscode/mcp.json` or via VS Code settings -**Windows**: `%APPDATA%\Code\User\mcp.json` + + + VS Code reads `.vscode/mcp.json` in your workspace, or the user-level file opened with **MCP: Open User Configuration** from the command palette. The key is `servers`, not `mcpServers`: -```json -{ - "mcpServers": { - "celo-mcp": { - "command": "uvx", - "args": ["--refresh", "celo-mcp"] + ```json + { + "servers": { + "celo-mcp": { + "command": "uvx", + "args": ["--refresh", "celo-mcp"] + } + } } - } -} -``` + ``` + + + + Add to `~/.cursor/mcp.json`: + + ```json + { + "mcpServers": { + "celo-mcp": { + "command": "uvx", + "args": ["--refresh", "celo-mcp"] + } + } + } + ``` + + `--refresh` makes `uvx` re-resolve the package so you pick up new releases. + + + + Add to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows: + + ```json + { + "mcpServers": { + "celo-mcp": { + "command": "uvx", + "args": ["--refresh", "celo-mcp"] + } + } + } + ``` + -### Cursor IDE Setup + + ```bash + claude mcp add celo-mcp -- uvx --refresh celo-mcp + ``` + -Add the following configuration to your MCP settings file (`~/.cursor/mcp.json`): + + Both configure MCP servers through their own settings UI rather than a file you edit directly. Use `uvx` as the command and `--refresh celo-mcp` as the arguments. + + -```json -{ - "mcpServers": { - "celo-mcp": { - "command": "uvx", - "args": ["--refresh", "celo-mcp"] - } - } -} +**Try it:** + +```text +Using the Celo MCP server, what is the current gas fee data on Celo mainnet? ``` -The `--refresh` flag ensures the latest code is always loaded when the MCP server starts. +## Available tools -### JetBrains IDEs Setup +### Network and blocks -For IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs, configure MCP through the IDE settings or via the JetBrains MCP Server plugin. +- **`get_network_status`** — current network status and connection information +- **`get_block`** — a block by number, hash, or `latest` +- **`get_latest_blocks`** — recent blocks, up to 100 +- **`get_transaction`** — transaction detail by hash -### Windsurf Setup +### Balances and fees -Windsurf has built-in MCP support. Configure MCP servers through the Windsurf settings interface. +- **`get_celo_balances`** — CELO plus the core Mento stablecoins (USDm, EURm, BRLm) for an address +- **`get_stable_token_balance`** — a wider set of tokens in one multicall: CELO, the Mento stablecoins, and USDC, USDT, USDGLO, cKES and others +- **`get_token_balance`** — the balance of one specific token for an address +- **`get_gas_fee_data`** — current gas fees, including EIP-1559 fields -### Claude Desktop Setup + +`USDm`, `EURm` and `BRLm` are the Mento stablecoins, formerly cUSD, cEUR and cREAL. `USDM` with a capital M is a different asset from a different issuer. + -For Claude Desktop, add this configuration to your MCP settings file: +### Governance -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` +- **`get_governance_proposals`** — governance proposals, paginated +- **`get_proposal_details`** — detail for one proposal -```json -{ - "mcpServers": { - "celo-mcp": { - "command": "uvx", - "args": ["--refresh", "celo-mcp"] - } - } -} -``` +### Staking and validators -### Connect Remotely (Streamable HTTP) +- **`get_staking_balances`** — staking balances for an address, by validator group +- **`get_activatable_stakes`** — pending stakes that can be activated for rewards +- **`get_total_staking_info`** — network-wide staking and participation metrics +- **`get_validator_groups`** — validator groups with members, votes, capacity and performance. **Paginated**, `page_size` defaults to 10, so a single call is not the full set +- **`get_validator_group_details`** — detail for one validator group -The server can also run as a remote MCP endpoint over Streamable HTTP, so clients connect with a single URL — no local Python install required. The stdio setup above is unchanged; this is an additional transport. +## Run as a remote HTTP endpoint -Run it in HTTP mode: +Running the server over Streamable HTTP lets clients connect with a single URL and no local Python install. This is server operation — if you only want the server on your own machine, the stdio configurations above are all you need. ```bash -celo-mcp-server --transport http --port 3000 -# or via env: -MCP_TRANSPORT=http PORT=3000 celo-mcp-server +celo-mcp-server --transport http --host 0.0.0.0 --port 3000 ``` -Then point any remote-capable MCP client at the URL: +`MCP_TRANSPORT`, `HOST` and `PORT` set the same three values from the environment. -```json -{ - "mcpServers": { - "celo-mcp": { "url": "https:///mcp" } - } -} -``` - -The HTTP transport is configured through environment variables: + +The defaults bind `127.0.0.1` and accept only localhost hostnames. A remote client against a default-configured server fails twice over: **connection refused**, because nothing listens on the public interface — fix with `--host 0.0.0.0` or `HOST`; then **HTTP 421 Misdirected Request**, because the DNS-rebinding check rejects the public hostname — fix by setting `MCP_ALLOWED_HOSTS` to that hostname. + | Variable | Purpose | Default | | --- | --- | --- | | `MCP_TRANSPORT` | `stdio` or `http` | `stdio` | -| `HOST` / `PORT` | HTTP bind host / port | `127.0.0.1` / `3000` | -| `MCP_ALLOWED_HOSTS` | Hostnames accepted by the SDK's DNS-rebinding check (comma-separated). Set to your public hostname(s), or `*` to disable | localhost only | -| `MCP_CORS_ORIGINS` | Comma-separated allowed origins (or `*`) | `*` | -| `MCP_RATE_LIMIT` / `MCP_RATE_WINDOW` | Requests per client per window (seconds); `/health` is exempt | `60` / `60` | -| `MCP_AUTH_TOKEN` | If set, requires `Authorization: Bearer ` on `/mcp` | unset (open) | - -`GET /health` returns `200` for hosting health checks. See the [repository's deployment guide](https://github.com/celo-org/celo-mcp/blob/main/docs/DEPLOYMENT.md) for container and hosting instructions. - -## Available Tools - -The server exposes read-only access to on-chain data. All tools are queries — the server does not sign or send transactions. - -### Network and Blocks - -- **`get_network_status`**: Get current network status and connection information -- **`get_block`**: Fetch block information by number, hash, or "latest" -- **`get_latest_blocks`**: Get information about recent blocks (up to 100) -- **`get_transaction`**: Get detailed transaction information by hash - -### Balances and Fees - -- **`get_celo_balances`**: Get CELO and stable token balances for an address -- **`get_stable_token_balance`**: Get balances of all major stable tokens and CELO for an address (multicall) -- **`get_token_balance`**: Get the balance of a specific token for an address -- **`get_gas_fee_data`**: Get current gas fee data including EIP-1559 fees - -### Governance - -- **`get_governance_proposals`**: Get Celo governance proposals with pagination -- **`get_proposal_details`**: Get detailed information about a specific governance proposal +| `HOST` / `PORT` | HTTP bind host and port | `127.0.0.1` / `3000` | +| `MCP_ALLOWED_HOSTS` | Hostnames accepted by the DNS-rebinding check, comma-separated. Set to your public hostname, or `*` to disable the check | localhost only | +| `MCP_CORS_ORIGINS` | Allowed origins, comma-separated, or `*` | `*` | +| `MCP_RATE_LIMIT` / `MCP_RATE_WINDOW` | Requests per client per window in seconds. `/health` is exempt | `60` / `60` | +| `MCP_TRUST_PROXY` | Number of trusted `X-Forwarded-For` hops. Behind a load balancer or Cloud Run, leaving this unset makes every client share one rate-limit bucket keyed on the proxy IP | unset | +| `MCP_AUTH_TOKEN` | If set, `/mcp` requires `Authorization: Bearer ` | unset, open | + +`GET /health` returns `200` for hosting health checks. + +Point a remote-capable client at the URL. The `type` field is required — an entry with a `url` and no `type` is read as a stdio server and silently skipped: + + + + ```bash + claude mcp add --transport http celo-mcp https:///mcp + ``` + + With `MCP_AUTH_TOKEN` set on the server: + + ```bash + claude mcp add --transport http celo-mcp https:///mcp \ + --header "Authorization: Bearer " + ``` + + + + ```json + { + "servers": { + "celo-mcp": { + "type": "http", + "url": "https:///mcp", + "headers": { "Authorization": "Bearer " } + } + } + } + ``` + + Drop `headers` if the server has no `MCP_AUTH_TOKEN`. + + + + ```json + { + "mcpServers": { + "celo-mcp": { + "type": "http", + "url": "https:///mcp", + "headers": { "Authorization": "Bearer " } + } + } + } + ``` + -### Staking and Validators + + Remote servers are added as **custom connectors** rather than through a config file: **Settings** → **Connectors** → **Add custom connector**, then paste the URL. -- **`get_staking_balances`**: Get staking balances for an address, broken down by validator group -- **`get_activatable_stakes`**: Get pending stakes that can be activated for rewards -- **`get_total_staking_info`**: Get network-wide staking information and participation metrics -- **`get_validator_groups`**: Get information about all validator groups (members, votes, capacity, performance) -- **`get_validator_group_details`**: Get detailed information about a specific validator group + Claude connects from Anthropic's infrastructure, not your machine, so the endpoint has to be reachable on the public internet. + + ## Development -### Running Tests - ```bash -# Install development dependencies +git clone https://github.com/celo-org/celo-mcp +cd celo-mcp pip install -e ".[dev]" -# Run tests -pytest +pytest # run tests +black src/ # format +ruff check src/ # lint +mypy src/ # type-check ``` -### Code Quality +## Resources -```bash -# Format code -black src/ +| Resource | Link | +|---|---| +| Source | [celo-org/celo-mcp](https://github.com/celo-org/celo-mcp) | +| Package | [celo-mcp on PyPI](https://pypi.org/project/celo-mcp/) | +| Deployment guide | [docs/DEPLOYMENT.md](https://github.com/celo-org/celo-mcp/blob/main/docs/DEPLOYMENT.md) | +| Model Context Protocol | [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction) | -# Lint and type-check -ruff check src/ -mypy src/ -``` +## Related -## Running the Server - -Start the MCP server directly: - -```bash -# Run the MCP server (stdio transport) -celo-mcp-server - -# Or run it as a remote HTTP endpoint -celo-mcp-server --transport http --port 3000 -``` +- [What is MCP?](/build-on-celo/build-with-ai/mcp/index) - how the protocol works and which Celo servers exist +- [Celo Docs MCP Server](/build-on-celo/build-with-ai/use-docs-with-ai) - search these docs from your editor +- [Celina](/build-on-celo/build-with-ai/mcp/celina) - an agent wallet, for the write side +- [Network information](/build-on-celo/network-overview) - chain IDs, RPC URLs and explorers diff --git a/build-on-celo/build-with-ai/use-docs-with-ai.mdx b/build-on-celo/build-with-ai/use-docs-with-ai.mdx index c78d19508..d801777d5 100644 --- a/build-on-celo/build-with-ai/use-docs-with-ai.mdx +++ b/build-on-celo/build-with-ai/use-docs-with-ai.mdx @@ -211,7 +211,7 @@ You can also skip the menu: **append `.md` to any docs URL** to get the Markdown - Query live chain data — balances, blocks, tokens, NFTs, and governance proposals — from your editor. + Query live chain data — blocks, transactions, balances, gas fees, governance and staking — from your editor. A skill that gives your coding assistant curated Celo knowledge: contract addresses, protocols, MiniPay, and grants. From cf9b5d70d3b401b0d92afbc56480d804bfe16db9 Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Thu, 3 Sep 2026 11:48:42 +0200 Subject: [PATCH 4/4] docs(mcp): say which symbols each balance tool reports, and note the pagination defaults get_celo_balances reads symbol() from each contract on chain and returns USDm, EURm and BRLm. get_stable_token_balance never calls symbol(); it builds each result from the server's built-in token table, which still says cUSD, cEUR and cREAL. The note under both bullets implied one set of symbols for both tools, so an agent reading the page as tool documentation would look for USDm in get_stable_token_balance output and read the balance as missing. Also record the count/offset parameters on get_latest_blocks and the page_size default on get_governance_proposals. All three checked against the published celo-mcp 0.4.1 wheel (server.py inputSchema, tokens/service.py). Co-Authored-By: Claude Fable 5.1 --- build-on-celo/build-with-ai/mcp/celo-mcp.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx index 635caf99a..d2ca26822 100644 --- a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx +++ b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx @@ -105,23 +105,23 @@ Using the Celo MCP server, what is the current gas fee data on Celo mainnet? - **`get_network_status`** — current network status and connection information - **`get_block`** — a block by number, hash, or `latest` -- **`get_latest_blocks`** — recent blocks, up to 100 +- **`get_latest_blocks`** — recent blocks; `count` defaults to 10 (max 100) and `offset` skips that many blocks back from the head - **`get_transaction`** — transaction detail by hash ### Balances and fees -- **`get_celo_balances`** — CELO plus the core Mento stablecoins (USDm, EURm, BRLm) for an address -- **`get_stable_token_balance`** — a wider set of tokens in one multicall: CELO, the Mento stablecoins, and USDC, USDT, USDGLO, cKES and others +- **`get_celo_balances`** — CELO plus the core Mento stablecoins for an address; symbols are read from each contract on chain, so they come back as `USDm`, `EURm` and `BRLm` +- **`get_stable_token_balance`** — a wider set of tokens in one multicall: CELO, the Mento stablecoins, and USDC, USDT, USDGLO, cKES and others; symbols come from the server's built-in token table, so the same three stablecoins are reported as `cUSD`, `cEUR` and `cREAL` - **`get_token_balance`** — the balance of one specific token for an address - **`get_gas_fee_data`** — current gas fees, including EIP-1559 fields -`USDm`, `EURm` and `BRLm` are the Mento stablecoins, formerly cUSD, cEUR and cREAL. `USDM` with a capital M is a different asset from a different issuer. +`USDm`, `EURm` and `BRLm` are the on-chain symbols of the Mento stablecoins, formerly `cUSD`, `cEUR` and `cREAL`. The two balance tools above name the same three assets differently, so match on the token address rather than the symbol when you combine their output. `USDM` with a capital M is a different asset from a different issuer. ### Governance -- **`get_governance_proposals`** — governance proposals, paginated +- **`get_governance_proposals`** — governance proposals, paginated; `page_size` defaults to 10 (max 20) - **`get_proposal_details`** — detail for one proposal ### Staking and validators