Shumi AI

@shumi-ai/mcp

Inteligência de trade de cripto da Shumi como um servidor MCP — a mesma inteligência de mercado que o shumi CLI oferece, para qualquer cliente MCP (Claude Desktop, Claude Code, Cursor, agentes).

É um wrapper leve sobre a API de dados da Shumi: preços, tendências, taxas de funding, sentimento, narrativas, regime de mercado, sinais sintetizados, ideias de par / delta-neutral, ativos do mundo real, rastreamento de holders e wallets, e destaques de transcrições. Todas as ferramentas são somente leitura.

Início rápido

Você precisa de uma chave de API da Shumi (shumi_sk_…). Crie uma em https://shumi.ai.

Claude Desktop / Claude Code

Adicione à sua configuração MCP (claude_desktop_config.json, ou claude mcp add para Claude Code):

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

Reinicie o cliente. As ferramentas shumi (ex.: get_coin_risk, get_market_health, ask_shumi) aparecem automaticamente.

Cursor

~/.cursor/mcp.json usa o mesmo formato command / args / env acima.

Diretórios de plugins

Este repositório também inclui plugin.json e mcp.json na raiz, então ele instala como um Agent Plugin a partir do diretório do Cursor e de qualquer outro cliente nesse padrão.

Defina SHUMI_TOKEN no seu ambiente antes de iniciar o cliente ao instalar dessa forma. O esquema de Agent Plugins aceita apenas valores literais de ambiente — não há espaço reservado para um segredo — então o manifesto omite deliberadamente env em vez de enviar uma string ${SHUMI_TOKEN} que seria repassada literalmente e falharia como chave inválida.

Ferramentas

Tipadas (determinísticas): 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.

Ativos do mundo real (list_rwa_assets, get_rwa_asset) cobrem ações, ETFs, commodities, índices e negociação de FX como perpétuos nas DEXes de builders da Hyperliquid. Eles não são tokens de cripto — as ferramentas de moedas não os encontrarão.

Forma livre: ask_shumi (perguntas em linguagem natural — a Shumi classifica, busca e sintetiza) e search_web.

Ferramentas que retornam listas aceitam top (manter os primeiros N itens) e fields (chaves separadas por vírgula para manter) para economizar tokens.

Recursos: shumi://capabilities (a superfície de dados) e shumi://billing/tier (sua permissão atual).

Configuração

Variável de ambiente	Padrão	Finalidade
SHUMI_TOKEN	—	Chave de API (shumi_sk_*). Obrigatória.
SHUMI_API_URL	endpoint de produção coinrotator-ai	Substituir a URL base da API.
SHUMI_WALLET	—	Endereço de wallet a incluir no contexto de consultas NLP.

A limitação (níveis gratuito / acesso / pro e pagamento por chamada) é aplicada no lado do servidor, exatamente como no CLI — respostas fora da cota retornam como um erro estruturado com uma dica acionável.

Remoto (HTTP)

Para uma implantação hospedada e multiusuário:

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

Cada requisição autentica com seu próprio cabeçalho de chave; esse token é encaminhado à API upstream por requisição. Endpoint: POST /mcp, health: GET /health.

Conectando a partir do Claude (static_headers)

O Claude suporta uma credencial fixa inserida como cabeçalho de requisição, então nenhum servidor OAuth é necessário. Em Adicionar conector personalizado → cabeçalhos de requisição, um administrador da organização insere:

campo	valor
URL	https://mcp.shumi.ai/mcp
Nome do cabeçalho	Authorization
Valor do cabeçalho	Bearer shumi_sk_…

x-api-key: shumi_sk_… também funciona, assim como um valor Authorization com o prefixo Bearer omitido — um administrador digita isso uma vez manualmente, e um par digitado errado falha de forma fechada sem erro visível, então todas as três formas são aceitas. x-api-key vence se ambos estiverem presentes, com base no princípio de que um administrador que o definiu o fez intencionalmente.

Não coloque a chave na URL. A especificação de autorização MCP proíbe tokens de acesso na string de consulta da URI, e a Anthropic documenta uma credencial em uma URL como vulnerabilidade de segurança — URLs caem em logs de servidor, proxies e histórico do navegador. As formas de consulta ?shumiToken= / ?config= existem apenas porque a Smithery injeta configuração de sessão dessa forma.

Uma coisa a saber antes de comprar para uma equipe: uma credencial static_headers é compartilhada pela organização, não por usuário. Todos que se conectam por esse conector compartilham uma conta Shumi, uma cota do nível gratuito e uma cota. A medição por usuário exige OAuth — veja docs/oauth-plan.md.

Uma chamada não autenticada é respondida com 200 e um erro AUTH_REQUIRED em banda, não 401. Isso é deliberado: o Claude trata um 401 como o início de um fluxo OAuth, e um servidor sem servidor de autorização por trás enviaria o cliente a um handshake que não pode ser concluído. O caminho 401 existe, mas está protegido por SHUMI_MCP_AUTH_SERVER, então ele só é ativado quando houver um servidor de autorização para apontar.

O servidor não tem estado. Um único endpoint atende ambas as revisões de protocolo:

• 2026-07-28 — sem initialize, sem Mcp-Session-Id. Uma requisição carrega seu próprio roteamento em cabeçalhos (Mcp-Method, além de Mcp-Name em tools/call) e seu envelope de protocolo em params._meta, então um intermediário pode rotear e medir uma chamada sem analisar o corpo.
• 2025-11-25 e anteriores — ainda atendidos. Clientes antigos mantêm seu handshake initialize, mas cada troca é respondida por sua própria instância, em vez de uma sessão.

Como nada sobrevive a uma requisição, GET e DELETE (as operações de sessão de 2025) retornam 405, e os ajustes de sessão que costumavam viver aqui — SHUMI_MCP_SESSION_TTL_MS, SHUMI_MCP_MAX_SESSIONS, SHUMI_MCP_SESSION_SWEEP_MS — foram removidos. Eles podem ser excluídos com segurança de qualquer implantação; sem definição, eles não fazem nada. O coletor de sessões ociosas que eles configuravam existia para impedir que probes de liveness aumentassem o heap, o que não pode acontecer quando nenhuma sessão é mantida.

Desenvolvimento

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

Deliberadamente não exposto

Duas rotas do CLI não têm ferramenta MCP, ambas de propósito:

• walkforward — a rota existe, mas duas de suas três ações não têm nada por trás enquanto o Engine B está pausado: positions está vazio e outcomes contém uma única linha de 2026-05-28. Enviá-la entregaria ao chamador um array vazio sem motivo anexado. Ela entra quando o engine for retomado.
• watch — server-sent events, que não se encaixam na semântica de ferramentas MCP.

Todo o resto na superfície tipada do CLI tem uma ferramenta.