> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shumi.ai/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](/agents/cli) and [API](/api-reference/introduction) 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

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>
</Tabs>

<Warning>
  Send the key as a header. Never put it in the URL. A URL is written to server logs, proxies and browser history.
</Warning>

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 31 tools. 29 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` |
| 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"`. [Market Screener](/research/market-screener) explains each sort and the fields each row carries.

| `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. [Coin Lookup](/research/coin-analysis#read-the-current-trend) explains the fields. A local server needs `@shumi-ai/mcp` 1.2.1 or later for both.

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`. It reports cuts made to keep the result small, but not the default 50-item cut on tools with the shared `top` filter |
| 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 walk-forward record or live streams | `shumi walkforward` and `shumi watch` in the [CLI](/agents/cli), or the [API](/api-reference/introduction#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. When the quota is used up, the tool returns an error with a hint on how to continue. [Plans and Quotas](/platform/access) explains the plans.

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