> ## Documentation Index
> Fetch the complete documentation index at: https://shumi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Give an AI agent Shumi's market data as MCP tools, hosted or run locally.

The Shumi MCP server exposes the same data the [CLI](https://shumi.mintlify.site/agents/cli.md) and [API](https://shumi.mintlify.site/api-reference/introduction.md) return, as tools an AI agent can call. You need an API key: run `shumi login`, then `shumi keys create`. Connect to the hosted server at `https://mcp.shumi.ai/mcp`, or run the `@shumi-ai/mcp` package locally with `npx`. Both serve the same tools against the same account and quota.

## Connect your client

> [tab] Claude (hosted)
>
> In Claude, choose **Add custom connector**, open the request headers section and enter:
>
> | Field | Value |
> | - | - |
> | URL | `https://mcp.shumi.ai/mcp` |
> | Header name | `Authorization` |
> | Header value | `Bearer shumi_sk_...` |
>
> `x-api-key` with the bare key as the value also works. Everyone who uses this connector shares the one Shumi account behind the key, and its quota.

> [tab] Claude Desktop
>
> Add this to `claude_desktop_config.json` and restart the app.
>
> ```json theme={"dark"}
> {
>   "mcpServers": {
>     "shumi": {
>       "command": "npx",
>       "args": ["-y", "@shumi-ai/mcp"],
>       "env": {
>         "SHUMI_TOKEN": "shumi_sk_your_key_here"
>       }
>     }
>   }
> }
> ```

> [tab] Claude Code
>
> Local:
>
> ```bash theme={"dark"}
> claude mcp add shumi -e SHUMI_TOKEN=shumi_sk_your_key_here -- npx -y @shumi-ai/mcp
> ```
>
> Hosted:
>
> ```bash theme={"dark"}
> claude mcp add --transport http shumi https://mcp.shumi.ai/mcp \
>   --header "Authorization: Bearer shumi_sk_your_key_here"
> ```

> [tab] Cursor
>
> Add this to `~/.cursor/mcp.json` and restart the app.
>
> ```json theme={"dark"}
> {
>   "mcpServers": {
>     "shumi": {
>       "command": "npx",
>       "args": ["-y", "@shumi-ai/mcp"],
>       "env": {
>         "SHUMI_TOKEN": "shumi_sk_your_key_here"
>       }
>     }
>   }
> }
> ```

> [tab] Any other client
>
> Any client that supports streamable HTTP servers connects with these settings.
>
> | Field | Value |
> | - | - |
> | URL | `https://mcp.shumi.ai/mcp` |
> | Transport | Streamable HTTP |
> | Header name | `Authorization` |
> | Header value | `Bearer shumi_sk_...` |

> [!WARNING]
>
> Send the key as a header. Never put it in the URL. A URL is written to server logs, proxies and browser history.

The local server reads three variables:

| Variable | Required | What it does |
| - | - | - |
| `SHUMI_TOKEN` | Yes | Your API key |
| `SHUMI_API_URL` | No | Point the server at a different API host |
| `SHUMI_WALLET` | No | A wallet address to include in plain-word question context |

`GET https://mcp.shumi.ai/health` answers without a key, so you can tell a bad key from a server that is down.

A missing or wrong key on the hosted server comes back as a normal response carrying an `AUTH_REQUIRED` error. If the tools appear but every call returns `AUTH_REQUIRED`, check the header name and value.

## Call a tool

There are 33 tools. 31 return data. `ask_shumi` and `search_web` return written answers.

| You want | Tools |
| - | - |
| One coin | `get_coin_risk`, `lookup_coin`, `resolve_coin`, `get_coin_sentiment`, `get_coin_historical` |
| The whole market | `get_market_health`, `get_global_market`, `get_market_crossing`, `get_prices`, `scan_trends`, `scan_coins` |
| Sentiment and narratives | `get_market_sentiment`, `list_narratives`, `get_narrative`, `list_categories`, `get_category` |
| Funding, regime and signals | `get_funding_momentum`, `get_funding_alerts`, `get_regime`, `get_signal`, `get_signal_quality`, `get_futures_signals` |
| Pairs | `get_pair_suggestions` |
| Token unlocks | `get_unlocks`, `get_unlock_calendar` |
| Stocks, metals, commodities, indices and FX as perps | `list_rwa_assets`, `get_rwa_asset` |
| Holders, wallets, baskets, transcripts | `get_holders`, `get_wallets`, `get_basket`, `get_transcripts` |
| A question in plain words | `ask_shumi`, `search_web` |

`get_coin_risk` takes 1 to 15 symbols at once. `resolve_coin` tells the token `GOLD` from the metal; resolve first when a ticker could mean two things. Real-world assets have their own two tools; the coin tools will not find them.

For "what's pumping today?", call `scan_coins` with `sort_by: "change24h"`.

| `scan_coins` input | Values |
| - | - |
| `sort_by` | `marketCap` (default), `change24h`, `change7d`, `streak`, `price` |
| `sort_order` | `desc` (default, largest first) or `asc` |
| `category` | One name from `list_categories` |
| `mcap_min`, `mcap_max` | Market-cap bounds in US dollars |

`lookup_coin` returns `currentTrend`: the coin's daily trend now, the day it started and how many days it has run. A local server needs `@shumi-ai/mcp` 1.2.1 or later for both, and 1.3.0 for the unlock tools.

Every list in a tool result holds 50 items at most, and fewer when the result is large.

| To | Use |
| - | - |
| Get fewer items | `top`, below 50 |
| Keep only some keys | `fields` |
| See whether a list was cut | `meta._truncated`. The default 50-item cap is not flagged here |
| Know the full count | Compare the list's length with `meta.total`, `total_count` or `count` where the result has one. `list_categories` and `scan_coins` have none |
| Get the full real-world asset list | `GET /api/cli/rwa/assets?top=1000` over the API |
| Read the signal track record or live streams | `shumi walkforward` and `shumi watch` in the [CLI](https://shumi.mintlify.site/agents/cli.md), or the [API](https://shumi.mintlify.site/api-reference/introduction.md#stream-live-data) |

Two resources describe the server: `shumi://capabilities` lists the tools, and `shumi://billing/tier` shows the plan on your key. On the Free plan every tool call counts as one question: 10 to start, then 1 per day. When the quota is used up, the tool returns an error with a hint on how to continue. Paid plans are in [Plans and Quotas](https://shumi.mintlify.site/platform/access.md).

## Ask a question with ask\_shumi

`ask_shumi` takes one `query` in plain words. Shumi works out which data it needs, fetches it and writes an answer, returned as plain text. Use it for a question that needs judgement or compares several things, such as "is funding on SOL crowded compared with last month?". For a fact with one exact answer, call the data tool instead: it is faster and returns the current figures without prose.

`search_web` takes a `query` and returns search results, or a written answer when `answer` is `true`.

## Read a result

A data tool returns `data` and `meta`. On most tools `meta.as_of` and `meta.data_age_seconds` say how old the data is. Check `data_age_seconds` before your agent acts on a funding rate or a price.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.