# @shumi-ai/mcp

Shumi crypto trade-intelligence as an [MCP](https://modelcontextprotocol.io) server — the same
market intelligence the [`shumi` CLI](https://www.npmjs.com/package/shumi) 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 <https://shumi.ai>.

### Claude Desktop / Claude Code

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

```json
{
  "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](https://agent-plugins.org) 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

| Env var | Default | Purpose |
| --- | --- | --- |
| `SHUMI_TOKEN` | — | API key (`shumi_sk_*`). **Required.** |
| `SHUMI_API_URL` | production coinrotator-ai endpoint | Override the API base URL. |
| `SHUMI_WALLET` | — | Wallet address to include in NLP query context. |

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:

```bash
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:

| field | value |
|---|---|
| URL | `https://mcp.shumi.ai/mcp` |
| Header name | `Authorization` |
| Header value | `Bearer shumi_sk_…` |

`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

```bash
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.