canton-mcp
Ask your AI about the Canton Network.
An [MCP](https://modelcontextprotocol.io) server for the
[Noves Canton API](https://docs.noves.fi/reference/welcome-canton-apis) — balances, rewards,
classified transactions, CC prices, identity, and the network directory, queryable from
Claude Code, Claude Desktop, Cursor, or any MCP-capable agent.
```text
You: How has the CC price moved over the last 7 days? Chart it.
AI: → get_price(startDate, endDate, interval: "daily")
CC closed at $0.1462 today, up 4.2% on the week (low $0.1402, high $0.1521).
[renders an interactive price chart]
```
## Quick start
Get your free API key at **https://app.noves.fi/register/free**.
### Claude Desktop — one click
Download `canton-mcp.mcpb` from the
[latest release](https://github.com/Noves-Inc/canton-mcp/releases/latest),
double-click it (or drag into Claude Desktop), and paste your API key in the
settings form that appears. The key is stored in your OS keychain. Done.
### Claude Code
```bash
npx -y @noves/canton-mcp init # one-time: prompts for your key, validates it, saves it
claude mcp add canton -- npx -y @noves/canton-mcp
```
Or in one line, passing the key explicitly:
```bash
claude mcp add canton --env NOVES_API_KEY= -- npx -y @noves/canton-mcp
```
### Cursor / other MCP clients
After `npx -y @noves/canton-mcp init`, no env var is needed:
```json
{
"mcpServers": {
"canton": {
"command": "npx",
"args": ["-y", "@noves/canton-mcp"]
}
}
}
```
(Or skip `init` and add `"env": { "NOVES_API_KEY": "" }`.)
**Key resolution order:** `NOVES_API_KEY` env var → `--api-key` flag →
`~/.config/canton-mcp/config.json`. The key is sent only to
`api.canton.noves.fi` and never logged.
## Tools
Every tool that takes a `party` accepts an **ANS name**, a **display name**, or a
**raw party ID** (`name::hash`) — resolution is automatic, and ambiguous names
return a candidate list to choose from.
Examples:
- "Who are the super validators on Canton?" → `search_directory(orgType: "sv")`
- "What's Noves' current CC balance?" → `get_balance(party: "noves.unverified.cns")`
- "Chart Noves' balance over the last 30 days." → `get_balance_history(party, startDate, endDate)`
- "Show recent traffic purchases for this validator." → `get_transactions(party, txType: "buyTraffic")`
| Tool | What it answers |
|---|---|
| `resolve_party` | "Who is this party?" — canonical party ID, org type, balance, ANS names |
| `search_directory` | "Who are the super validators?" — browse/filter the network directory |
| `get_balance` | "What's this party's balance?" — current **or at any point in time** (`date`) |
| `get_balance_history` | "Chart its balance over last month" — daily end-of-day snapshots |
| `get_rewards` | "What did it earn?" — summary metrics, per-day totals, or individual payouts |
| `get_transactions` | "Show its recent traffic purchases" — classified history (transfer, buyTraffic, …) |
| `get_transfer_stats` | "How active is it?" — counts, volumes, unique counterparties |
| `get_price` | "CC price trend this month?" — spot, historical spot, hourly/daily OHLC |
| `get_transaction` | Full classified payload of one update by ID |
See [examples/PROMPTS.md](examples/PROMPTS.md) for questions to try.
### Notes & limits
- **Read-only.** The server only reads data; it can't change anything on the network or in your account.
- Date inputs accept ISO dates (`2026-06-01`), ISO datetimes, or unix timestamps.
- Daily rewards are fetched in ≤30-day windows upstream; the server merges up to 90 days per call.
- List outputs are capped (default 25 rows) with `hasMore` hints to keep agent context lean.
- `get_transactions` returns 25 rows by default and accepts `limit` up to 100; use
`includeCount` for the total count in a date window, and `get_transaction` for one full update.
- Chains/txTypes (1h), directory & identity lookups (5m), and spot price (60s) are cached
in-process, keeping typical agent sessions comfortably inside the free tier.
## License
[MIT](LICENSE) © Noves Inc.
