RiskState

Servidor MCP RiskState

Servidor MCP para RiskState — permissões de risco pré-negociação para BTC/USD e ETH/USD. Consciente de mercado à vista, futuros perpétuos (perps) e empréstimos DeFi.

Seu sistema pergunta: "Quanto posso arriscar agora?" O RiskState responde com: nível de política, exposição máxima, limites de alavancagem, ações bloqueadas — calculados a partir de mais de 30 sinais em tempo real.

Duas formas de usar o RiskState via MCP

1. Conector remoto — sem instalação, sem chave de API. O RiskState executa um servidor MCP hospedado (HTTP Streamable) com um nível público gratuito:

https://api.riskstate.ai/mcp

Adicione-o como conector personalizado no Claude ou ChatGPT e basta perguntar qual é o estado de risco do BTC. Ele expõe três ferramentas somente leitura — get_risk_state, get_market_structure, get_playbook_status — cobrindo os três mecanismos, e está listado no registro oficial MCP como ai.riskstate/mcp.

As respostas são o resumo público gratuito: a mesma altitude do visualizador público. policy_hash, subpontuações compostas, detalhes de posicionamento e macro exigem uma chave.

2. Este pacote — stdio, com chave, resposta completa. Use-o quando quiser o payload auditado completo em um agente local, ou para fixar uma versão em sua própria ferramenta. Ele precisa de um RISKSTATE_API_KEY e retorna tudo a que sua chave tem direito. É isso que o restante deste README cobre.

Ferramentas

Quatro ferramentas somente leitura, uma para cada pergunta que você pode fazer antes de uma negociação:

Ferramenta	Responde	Endpoint	Chave
get_risk_policy	Quanta exposição é permitida?	POST /v1/risk-state	sim
get_market_structure	Estamos perto de uma inflexão estrutural?	POST /v1/market-structure	sim
get_playbook_status	Uma configuração é acionável agora?	GET /api/playbook-data	não
check_trade	ESTA posição seria permitida?	POST /v2/portfolio-risk-state	sim

get_risk_policy retorna:

Campo	Descrição
policy_level	5 níveis: BLOCK_SURVIVAL, BLOCK_DEFENSIVE, CAUTIOUS, GREEN_SELECTIVE, GREEN_EXPANSION
max_size_pct	Tamanho máximo da posição como % do portfólio (0-100)
leverage_max	Multiplicador máximo de alavancagem permitido
allowed_actions	O que o agente PODE fazer neste nível de política
blocked_actions	O que o agente NÃO PODE fazer
confidence_score	Concordância de sinais x qualidade dos dados (0-1)

check_trade avalia um livro hipotético — envie a posição que você está considerando mais qualquer coisa que você já detém, pois os limites consideram o portfólio. Ele retorna por posição se é permitida, o limite de tamanho em percentual e dólares, e reason_codes quando não é. Esses são bloqueadores; advisories são informativos e não afetam allowed. Ele não coloca ordens.

get_playbook_status reporta uma configuração como acionável somente quando suas condições correspondem, nenhum mecanismo a vetou, e ela não está em período de espera de alerta. Configurações que correspondem mas já alertaram são contadas separadamente, para que um agente que consulte esta ferramenta não aja duas vezes sobre o mesmo sinal.

Por que não há ferramentas de escrita

Não há update_policy, não há set_limit, não há gerenciamento de exceções — e não haverá. A premissa do RiskState é que o sistema governado não pode mover seus próprios limites. Cada decisão é hashada (policy_hash) para que possa ser auditada posteriormente contra as entradas que a produziram; uma ferramenta que permitisse ao chamador reescrever a política tornaria esse hash sem sentido e o rastro de auditoria decorativo.

Portanto, o ciclo de vida aqui vive deliberadamente de um lado: o mecanismo calcula, o agente lê e cumpre. check_trade é o mais próximo de uma operação dinâmica por negociação, e ainda é somente leitura — ele responde "isso seria permitido", nunca "permita isso".

A API agrega 9+ fontes de dados em tempo real no lado do servidor. Consulte documentação da API para detalhes.

O que este wrapper faz (e não faz)

Este é um wrapper fino — ele traduz chamadas de ferramentas MCP em solicitações REST API e retorna a resposta. Toda a computação (pontuação, mecanismo de política, ingestão de dados) acontece no lado do servidor.

Este wrapper adiciona:

• Conformidade com o protocolo MCP (transporte stdio para Claude Desktop/Code)
• Validação de entrada via esquemas Zod
• Resumo de política legível por humanos prefixado às respostas
• Mensagens de erro específicas (autenticação, limite de taxa, timeout) para recuperação do agente

Este wrapper NÃO:

• Armazena respostas em cache (a API tem cache de 60s no lado do servidor)
• Realiza qualquer pontuação ou computação localmente
• Garante estabilidade do esquema de resposta (segue o versionamento da API)

Instalação

npm install @riskstate/mcp-server

Configuração

Variáveis de Ambiente

Variável	Obrigatória	Descrição
RISKSTATE_API_KEY	Sim	Chave de API de riskstate.ai (gratuita durante o beta)
RISKSTATE_API_URL	Não	URL base personalizada da API (padrão: https://api.riskstate.ai)

Claude Desktop

Adicione ao ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "riskstate": {
      "command": "npx",
      "args": ["-p", "@riskstate/mcp-server", "riskstate-mcp"],
      "env": {
        "RISKSTATE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add riskstate -- npx -p @riskstate/mcp-server riskstate-mcp

Defina a chave de API no seu ambiente:

export RISKSTATE_API_KEY=your-api-key

Instalação global (alternativa)

npm install -g @riskstate/mcp-server
riskstate-mcp  # starts MCP server on stdio

Uso

As quatro ferramentas estão listadas acima. get_risk_policy recebe:

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
asset	"BTC" | "ETH"	Sim	Ativo a analisar
wallet_address	string	Não	Carteira DeFi para dados de posição on-chain
protocol	"spark" | "aave"	Não	Protocolo de empréstimo (padrão: spark)
include_details	boolean	Não	Incluir detalhamento completo (subpontuações, macro, sinalizadores de risco)

Exemplo de Resposta

{
  "exposure_policy": {
    "policy_level": "CAUTIOUS",
    "max_size_pct": 35,
    "leverage_max": 1.5,
    "allowed_actions": ["DCA", "WAIT", "SPOT_LONG_CONFIRMED"],
    "blocked_actions": ["LEVERAGE_GT_2X", "NEW_POSITIONS_UNCONFIRMED"]
  },
  "classification": {
    "cycle_phase": "MID",
    "market_regime": "RANGE",
    "macro_regime": "NEUTRAL",
    "direction": "SIDEWAYS"
  },
  "auditability": {
    "composite_score": 52,
    "confidence_score": 0.72,
    "policy_hash": "a3f8c2...",
    "ttl_seconds": 60
  }
}

Como os Agentes Devem Usar Isso

Chame get_risk_policy antes de cada negociação:

1. Se policy_level começar com BLOCK → não abra novas posições
2. Use max_size_pct para limitar o tamanho da posição
3. Verifique blocked_actions antes de executar
4. Consulte novamente após ttl_seconds (cache de 60s)

Para uma posição dimensionada, check_trade combina as etapas 2-3 em uma única chamada: envie a posição que pretende abrir junto com o que já detém, e leia allowed mais reason_codes. Prefira-a em vez de derivar o limite você mesmo, pois os limites consideram o portfólio e uma posição que passa isoladamente ainda pode violar a concentração quando agregada.

get_market_structure e get_playbook_status são contexto, não permissão. Nenhum deles autoriza uma negociação — apenas a política de risco o faz. Use-os para decidir se vale a pena propor uma negociação, depois get_risk_policy / check_trade para saber quanto dela você tem permissão.

Limitações

• Escopo v1: apenas BTC/USD e ETH/USD (avaliação denominada em USD). Mais ativos planejados.
• Mercados: mercado à vista, futuros perpétuos e empréstimos DeFi. Mesma resposta — interpretação difere por mercado (consulte documentação da API).
• Protocolos: apenas Spark e Aave V3 para dados de posição DeFi.
• Limite de taxa: 60 solicitações/minuto por chave de API.
• Latência: ~1-3s por solicitação (agregação de 9+ fontes de dados upstream).
• Testado com: Claude Desktop, Claude Code. Deve funcionar com qualquer cliente compatível com MCP.

Links

• Página inicial: riskstate.ai
• Documentação da API: riskstate.ai/docs/api
• SKILL.md: agentskills.io

Licença

MIT