{
  "markdown": "# @shumi-ai/mcp\n\nShumi crypto trade-intelligence as an [MCP](https://modelcontextprotocol.io) server — the same\nmarket intelligence the [`shumi` CLI](https://www.npmjs.com/package/shumi) provides, for any MCP\nclient (Claude Desktop, Claude Code, Cursor, agents).\n\nIt's a thin wrapper over Shumi's data API: prices, trends, funding rates, sentiment, narratives,\nmarket regime, synthesized signals, pair / delta-neutral ideas, real-world assets, holder and\nwallet tracking, and transcript highlights. All tools are read-only.\n\n## Quick start\n\nYou need a Shumi API key (`shumi_sk_…`). Create one at <https://shumi.ai>.\n\n### Claude Desktop / Claude Code\n\nAdd to your MCP config (`claude_desktop_config.json`, or `claude mcp add` for Claude Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"shumi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@shumi-ai/mcp\"],\n      \"env\": {\n        \"SHUMI_TOKEN\": \"shumi_sk_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nRestart the client. The `shumi` tools (e.g. `get_coin_risk`, `get_market_health`, `ask_shumi`)\nappear automatically.\n\n### Cursor\n\n`~/.cursor/mcp.json` uses the same `command` / `args` / `env` shape as above.\n\n### Plugin directories\n\nThis repo also ships `plugin.json` and `mcp.json` at its root, so it installs as an\n[Agent Plugin](https://agent-plugins.org) from Cursor's directory and any other client on that\nstandard.\n\nSet `SHUMI_TOKEN` in your environment before starting the client when you install this way. The\nAgent Plugins schema takes literal environment values only — it has no placeholder for a secret —\nso the manifest deliberately omits `env` rather than shipping a `${SHUMI_TOKEN}` string that would\nbe passed through verbatim and fail as an invalid key.\n\n## Tools\n\n**Typed (deterministic):** `get_coin_risk`, `lookup_coin`, `resolve_coin`, `get_coin_sentiment`,\n`get_coin_historical`, `get_market_health`, `get_market_crossing`, `get_global_market`,\n`get_prices`, `scan_trends`, `scan_coins`, `get_market_sentiment`, `list_narratives`,\n`get_narrative`, `list_categories`, `get_category`, `get_funding_momentum`, `get_funding_alerts`,\n`get_regime`, `get_signal`, `get_signal_quality`, `get_pair_suggestions`, `list_rwa_assets`,\n`get_rwa_asset`, `get_holders`, `get_wallets`, `get_futures_signals`, `get_basket`,\n`get_transcripts`.\n\n**Real-world assets** (`list_rwa_assets`, `get_rwa_asset`) cover stocks, ETFs, commodities,\nindices and FX trading as perps on Hyperliquid builder DEXes. They are not crypto tokens — the\ncoin tools will not find them.\n\n**Free-form:** `ask_shumi` (natural-language questions — Shumi classifies, fetches, and synthesizes)\nand `search_web`.\n\nList-returning tools accept `top` (keep first N items) and `fields` (comma-separated keys to keep)\nto save tokens.\n\n**Resources:** `shumi://capabilities` (the data surface) and `shumi://billing/tier` (your current\nentitlement).\n\n## Configuration\n\n| Env var | Default | Purpose |\n| --- | --- | --- |\n| `SHUMI_TOKEN` | — | API key (`shumi_sk_*`). **Required.** |\n| `SHUMI_API_URL` | production coinrotator-ai endpoint | Override the API base URL. |\n| `SHUMI_WALLET` | — | Wallet address to include in NLP query context. |\n\nGating (free / access / pro tiers and pay-per-call) is enforced server-side, exactly as for the CLI —\nout-of-quota responses come back as a structured error with an actionable hint.\n\n## Remote (HTTP)\n\nFor a hosted, multi-user deployment:\n\n```bash\nPORT=8787 SHUMI_MCP_ALLOWED_ORIGINS=https://yourapp.com npm run start:http\n```\n\nEach request authenticates with its own key header; that token is forwarded to the upstream API per\nrequest. Endpoint: `POST /mcp`, health: `GET /health`.\n\n### Connecting from Claude (`static_headers`)\n\nClaude supports a fixed credential entered as a request header, so no OAuth server is needed. In\n**Add custom connector → request headers**, an organisation administrator enters:\n\n| field | value |\n|---|---|\n| URL | `https://mcp.shumi.ai/mcp` |\n| Header name | `Authorization` |\n| Header value | `Bearer shumi_sk_…` |\n\n`x-api-key: shumi_sk_…` works too, and so does an `Authorization` value with the `Bearer ` prefix\nomitted — an admin types this once by hand, and a mistyped pair fails closed with no error they can\nsee, so all three shapes are accepted. `x-api-key` wins if both are present, on the grounds that an\nadmin who set it meant it.\n\n**Do not put the key in the URL.** The MCP authorization spec prohibits access tokens in the URI\nquery string and Anthropic documents a credential in a URL as a security vulnerability — URLs land in\nserver logs, proxies and browser history. The `?shumiToken=` / `?config=` query forms exist only\nbecause Smithery injects session config that way.\n\nOne thing to know before buying for a team: a `static_headers` credential is **shared by the\norganisation, not per user**. Everyone connecting through that connector shares one Shumi account,\none free-tier allowance and one quota. Per-user metering needs OAuth — see `docs/oauth-plan.md`.\n\nAn unauthenticated call is answered with **`200` and an in-band `AUTH_REQUIRED` error, not `401`**.\nThat is deliberate: Claude treats a `401` as the start of an OAuth flow, and a server with no\nauthorization server behind it would send the client into a handshake that cannot complete. The\n`401` path exists but is gated behind `SHUMI_MCP_AUTH_SERVER`, so it lights up only once there is an\nauthorization server to point at.\n\n**The server is stateless.** One endpoint serves both protocol revisions:\n\n- **`2026-07-28`** — no `initialize`, no `Mcp-Session-Id`. A request carries its own routing in\n  headers (`Mcp-Method`, plus `Mcp-Name` on `tools/call`) and its protocol envelope in `params._meta`,\n  so an intermediary can route and meter a call without parsing the body.\n- **`2025-11-25` and earlier** — still served. Old clients keep their `initialize` handshake, but each\n  exchange is answered by its own instance rather than a session.\n\nBecause nothing outlives a request, `GET` and `DELETE` (the 2025 session operations) return `405`,\nand the session tunables that used to live here — `SHUMI_MCP_SESSION_TTL_MS`, `SHUMI_MCP_MAX_SESSIONS`,\n`SHUMI_MCP_SESSION_SWEEP_MS` — are gone. They are safe to delete from any deployment; unset they do\nnothing. The idle-session reaper they configured existed to stop liveness probes from growing the\nheap, which cannot happen when no session is kept.\n\n## Develop\n\n```bash\nnpm install\nnpm test                # unit tests (no network)\nnpm run inspect         # open the MCP Inspector against the stdio server\nSHUMI_TOKEN=… npm start # run the stdio server\n```\n\n## Deliberately not exposed\n\nTwo CLI routes have no MCP tool, both on purpose:\n\n- **`walkforward`** — the route exists, but two of its three actions have nothing behind them\n  while Engine B is paused: positions is empty and outcomes holds a single row from 2026-05-28.\n  Shipping it would hand a caller an empty array with no reason attached. It goes in when the\n  engine resumes.\n- **`watch`** — server-sent events, which do not fit MCP tool semantics.\n\nEverything else in the CLI's typed surface has a tool.\n",
  "bytes": 7074,
  "sha": "c12c4df8bab78801f45f273a22d03c186b30664c2420b46d52c09035bcb73bf0",
  "repo_slug": "shumi-ai/shumi-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_shumi_mcp_1a260480/readme"
}