@shumi-ai/mcp

Shumi crypto trade-intelligence as an MCP server — the same

market intelligence the `shumi` CLI provides, for any MCP

client (Claude Desktop, Claude Code, Cursor, agents).

It's a thin wrapper over Shumi's data API: prices, trends, funding rates, sentiment, narratives,

market regime, synthesized signals, pair / delta-neutral ideas, real-world assets, holder and

wallet tracking, and transcript highlights. All tools are read-only.

Quick start

You need a Shumi API key (`shumi_sk_…`). Create one at .

Claude Desktop / Claude Code

Add to your MCP config (`claude_desktop_config.json`, or `claude mcp add` for Claude Code):

{
  "mcpServers": {
    "shumi": {
      "command": "npx",
      "args": ["-y", "@shumi-ai/mcp"],
      "env": {
        "SHUMI_TOKEN": "shumi_sk_your_key_here"
      }
    }
  }
}

Restart the client. The `shumi` tools (e.g. `get_coin_risk`, `get_market_health`, `ask_shumi`)

appear automatically.

Cursor

`~/.cursor/mcp.json` uses the same `command` / `args` / `env` shape as above.

Plugin directories

This repo also ships `plugin.json` and `mcp.json` at its root, so it installs as an

Agent Plugin from Cursor's directory and any other client on that

standard.

Set `SHUMI_TOKEN` in your environment before starting the client when you install this way. The

Agent Plugins schema takes literal environment values only — it has no placeholder for a secret —

so the manifest deliberately omits `env` rather than shipping a `${SHUMI_TOKEN}` string that would

be passed through verbatim and fail as an invalid key.

Tools

Typed (deterministic): `get_coin_risk`, `lookup_coin`, `resolve_coin`, `get_coin_sentiment`,

`get_coin_historical`, `get_market_health`, `get_market_crossing`, `get_global_market`,

`get_prices`, `scan_trends`, `scan_coins`, `get_market_sentiment`, `list_narratives`,

`get_narrative`, `list_categories`, `get_category`, `get_funding_momentum`, `get_funding_alerts`,

`get_regime`, `get_signal`, `get_signal_quality`, `get_pair_suggestions`, `list_rwa_assets`,

`get_rwa_asset`, `get_holders`, `get_wallets`, `get_futures_signals`, `get_basket`,

`get_transcripts`.

Real-world assets (`list_rwa_assets`, `get_rwa_asset`) cover stocks, ETFs, commodities,

indices and FX trading as perps on Hyperliquid builder DEXes. They are not crypto tokens — the

coin tools will not find them.

Free-form: `ask_shumi` (natural-language questions — Shumi classifies, fetches, and synthesizes)

and `search_web`.

List-returning tools accept `top` (keep first N items) and `fields` (comma-separated keys to keep)

to save tokens.

Resources: `shumi://capabilities` (the data surface) and `shumi://billing/tier` (your current

entitlement).

Configuration

Gating (free / access / pro tiers and pay-per-call) is enforced server-side, exactly as for the CLI —

out-of-quota responses come back as a structured error with an actionable hint.

Remote (HTTP)

For a hosted, multi-user deployment:

PORT=8787 SHUMI_MCP_ALLOWED_ORIGINS=https://yourapp.com npm run start:http

Each request authenticates with its own key header; that token is forwarded to the upstream API per

request. Endpoint: `POST /mcp`, health: `GET /health`.

Connecting from Claude (`static_headers`)

Claude supports a fixed credential entered as a request header, so no OAuth server is needed. In

Add custom connector → request headers, an organisation administrator enters:

`x-api-key: shumi_sk_…` works too, and so does an `Authorization` value with the `Bearer ` prefix

omitted — an admin types this once by hand, and a mistyped pair fails closed with no error they can

see, so all three shapes are accepted. `x-api-key` wins if both are present, on the grounds that an

admin who set it meant it.

Do not put the key in the URL. The MCP authorization spec prohibits access tokens in the URI

query string and Anthropic documents a credential in a URL as a security vulnerability — URLs land in

server logs, proxies and browser history. The `?shumiToken=` / `?config=` query forms exist only

because Smithery injects session config that way.

One thing to know before buying for a team: a `static_headers` credential is **shared by the

organisation, not per user**. Everyone connecting through that connector shares one Shumi account,

one free-tier allowance and one quota. Per-user metering needs OAuth — see `docs/oauth-plan.md`.

An unauthenticated call is answered with `200` and an in-band `AUTH_REQUIRED` error, not `401`.

That is deliberate: Claude treats a `401` as the start of an OAuth flow, and a server with no

authorization server behind it would send the client into a handshake that cannot complete. The

`401` path exists but is gated behind `SHUMI_MCP_AUTH_SERVER`, so it lights up only once there is an

authorization server to point at.

The server is stateless. One endpoint serves both protocol revisions:

• `2026-07-28` — no `initialize`, no `Mcp-Session-Id`. A request carries its own routing in

headers (`Mcp-Method`, plus `Mcp-Name` on `tools/call`) and its protocol envelope in `params._meta`,

so an intermediary can route and meter a call without parsing the body.

• `2025-11-25` and earlier — still served. Old clients keep their `initialize` handshake, but each

exchange is answered by its own instance rather than a session.

Because nothing outlives a request, `GET` and `DELETE` (the 2025 session operations) return `405`,

and the session tunables that used to live here — `SHUMI_MCP_SESSION_TTL_MS`, `SHUMI_MCP_MAX_SESSIONS`,

`SHUMI_MCP_SESSION_SWEEP_MS` — are gone. They are safe to delete from any deployment; unset they do

nothing. The idle-session reaper they configured existed to stop liveness probes from growing the

heap, which cannot happen when no session is kept.

Develop

npm install
npm test                # unit tests (no network)
npm run inspect         # open the MCP Inspector against the stdio server
SHUMI_TOKEN=… npm start # run the stdio server

Deliberately not exposed

Two CLI routes have no MCP tool, both on purpose:

• `walkforward` — the route exists, but two of its three actions have nothing behind them

while Engine B is paused: positions is empty and outcomes holds a single row from 2026-05-28.

Shipping it would hand a caller an empty array with no reason attached. It goes in when the

engine resumes.

• `watch` — server-sent events, which do not fit MCP tool semantics.

Everything else in the CLI's typed surface has a tool.