io.github.Noves-Inc/canton-mcp

Query Canton Network balances, rewards, transactions, prices, and identity from any AI agent.

Open source Open in the app JSON README (API)

About

Query Canton Network balances, rewards, transactions, prices, and identity from any AI agent.

Details

Kind: MCP servers
Topic: Security & identity
Publisher: noves-inc
Origin: official
Category: ferramentas
Transport: local
Version: 0.2.3
Last push: 2026-06-05T20:37:34Z
Repository state: ativo
Language: TypeScript
License: MIT
Added: 2026-08-29 03:02:08
Updated: 2026-08-29 03:02:08
Origin id: io.github.Noves-Inc/canton-mcp

README

<p align="center">
  <a href="https://noves.fi">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="assets/noves-logo-white.svg">
      <img src="assets/noves-logo-primary.svg" alt="Noves" width="260">
    </picture>
  </a>
</p>

<h1 align="center">canton-mcp</h1>

<p align="center"><strong>Ask your AI about the Canton Network.</strong></p>

<p align="center">
  <a href="https://www.npmjs.com/package/@noves/canton-mcp"><img src="https://img.shields.io/npm/v/%40noves%2Fcanton-mcp?label=npm&color=cb3837" alt="npm version"></a>
  <a href="https://github.com/Noves-Inc/canton-mcp/actions/workflows/ci.yml"><img src="https://github.com/Noves-Inc/canton-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://registry.modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP_Registry-listed-6e56cf" alt="MCP Registry"></a>
  <a href="LICENSE"><img src="https://img.shields.io/npm/l/%40noves%2Fcanton-mcp?color=blue" alt="MIT license"></a>
</p>

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=<your-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": "<your-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.