StackSpend MCP

npx add-mcp 'https://api.stackspend.app/api/v1/mcp'

O que faz

O servidor MCP StackSpend MCP implementa o Model Context Protocol para que o Claude Code possa ler seus dados do StackSpend como contexto. Uma vez configurado, você pode perguntar sobre seus custos de nuvem e IA — por provedor, serviço, modelo, projeto, usuário, intervalo de datas ou anomalia — e obter respostas baseadas nos seus gastos reais.

As ferramentas de leitura cobrem resumos de gastos, previsões em relação ao orçamento, saúde dos provedores, totais consolidados, itens de linha, anomalias e tarefas. As ferramentas de escrita permitem que o Claude faça triagem de uma anomalia ou abra uma tarefa para o time — somente quando você pedir explicitamente.

Plano Business obrigatório. O servidor MCP usa a API pública do StackSpend, que exige uma assinatura do plano Business.

Configuração

1

Crie uma chave de API

Vá em Configurações → API e clique em Criar chave de API. Dê um nome como "Claude Code MCP". Novas chaves incluem os escopos que o servidor MCP precisa:

• spend:read, providers:read, rollups:read, line_items:read, anomalies:read, tasks:read
• anomalies:write e tasks:write para as ações de triagem

Copie a chave — ela é exibida apenas uma vez. Guarde-a em um local seguro.

Adicione o servidor ao Claude Code

A forma mais rápida é pela CLI do Claude Code:

claude mcp add stackspend --env STACKSPEND_API_KEY=your_api_key_here -- npx -y @stackspend/mcp-server

Ou adicione manualmente em ~/.claude.json (todos os projetos) ou .mcp.json na raiz do seu projeto (compartilhado com seu time):

{
  "mcpServers": {
    "stackspend": {
      "command": "npx",
      "args": ["-y", "@stackspend/mcp-server"],
      "env": {
        "STACKSPEND_API_KEY": "your_api_key_here"
      }
    }
  }
}

Dica. O mesmo bloco mcpServers funciona no Claude Desktop, no próprio arquivo de configuração dele.

3

Reinicie o Claude Code

Reabra o Claude Code e execute /mcp. Você deve ver stackspend listado como conectado.

O que você pode perguntar

• "Estamos dentro do orçamento este mês?"
• "Quanto gastei na AWS este mês e a conexão está saudável?"
• "Quais modelos da OpenAI são os mais caros?"
• "Há alguma anomalia em aberto? O que causou a maior?"
• "Qual serviço teve o maior aumento de custo na semana passada?"
• "Abra uma tarefa para redimensionar aquela instância e atribua a mim."

Ferramentas

Gastos e previsão

Ferramenta	Escopo	O que retorna
get_spend_summary	spend:read	Ontem, últimos 7 dias, últimos 30 dias e do início do mês até hoje, cada um com tendência e status, para o portfólio e por provedor. Inclui a data mais recente dos dados para você diferenciar conexões desatualizadas de gastos realmente baixos.
get_forecast	spend:read	Projeção de fim de mês em relação ao orçamento, dias até estourar o orçamento e ritmo e momentum por provedor.
get_savings	spend:read	Excesso de gasto evitado ao resolver anomalias, neste mês e no total acumulado.
get_providers	providers:read	Saúde da conexão: última sincronização, último erro, se um provedor precisa ser reconectado.

Dados de custo

Ferramenta	Escopo	O que retorna
get_daily_rollups	rollups:read	Totais diários agrupados por provedor, serviço, categoria, projeto, usuário, conta ou modelo.
get_line_items	line_items:read	Itens de linha brutos, com paginação por cursor, filtráveis por qualquer dimensão, incluindo modelo.

Anomalias

Ferramenta	Escopo	O que retorna
get_anomalies	anomalies:read	Picos de gasto detectados com excesso, status e — com controle de versão conectado — o provável PR que contribuiu.
get_anomaly_detail	anomalies:read	O log de mudanças ranqueado de uma anomalia: PRs e deploys com confiança, evidências e arquivos alterados.
update_anomaly_status	anomalies:write	Reconhecer, resolver, descartar ou marcar como falso positivo. Resolver ou descartar exige uma nota.
set_anomaly_severity	anomalies:write	Repriorizar uma anomalia.
add_anomaly_comment	anomalies:write	Comentar em um tópico de anomalia.

Tarefas

Ferramenta	Escopo	O que retorna
list_tasks	tasks:read	Tarefas de FinOps: revisões de orçamento, oportunidades de otimização, acompanhamentos de economia e recomendações de modelo.
create_task	tasks:write	Criar uma tarefa de otimização, sincronizada com um projeto Jira ou Linear conectado.
update_task	tasks:write	Transicionar uma tarefa até o status de concluída.

Ferramentas de escrita exigem instrução explícita. O Claude não fechará uma anomalia nem abrirá uma tarefa por conta própria. Resolver ou descartar uma anomalia exige uma nota, e toda escrita é atribuída ao dono da chave de API.

MCP hospedado (OAuth)

Para clientes que precisam de uma URL MCP remota em vez de um comando local — conectores personalizados do Claude, por exemplo — o StackSpend pode expor as mesmas ferramentas via OAuth. Crie um cliente OAuth em Configurações → API e aponte seu cliente para:

https://api.stackspend.app/api/v1/mcp

Os metadados de descoberta são servidos de /.well-known/oauth-authorization-server e /.well-known/oauth-protected-resource no mesmo host. O fluxo é código de autorização com PKCE.

Habilitado por padrão. O MCP hospedado está ativo, a menos que sua implantação o tenha desativado. Se a descoberta retornar HOSTED_MCP_DISABLED, use a configuração local acima ou entre em contato com o suporte.

Prompts

Clientes que suportam prompts MCP recebem quatro fluxos de trabalho guiados. Cada um sequencia as ferramentas certas e instrui o modelo a verificar a atualidade dos dados antes de confiar em um número.

Prompt	O que faz
cost_review	Onde os gastos estão, o que mudou e o que fazer — opcionalmente para um período nomeado
explain_anomaly	Diagnosticar um pico a partir do log de mudanças, ou pegar o maior em aberto
find_savings	Gastos redutíveis e oportunidades já registradas, ranqueadas por economia anualizada
check_connections	Verificar se os dados estão fluindo antes de confiar em qualquer número

Moeda

Os valores retornam na moeda de exibição da sua organização, indicada na resposta. cost e net_amount são convertidos; cost_usd e net_amount_usd permanecem em USD, para que um script que já lê os campos em USD continue funcionando.

Solução de problemas

• Servidor não listado em /mcp — verifique se o arquivo de configuração que você editou é ~/.claude.json ou .mcp.json, e se o bloco está nomeado como mcpServers.
• Conexão recusada ou timeout — defina STACKSPEND_API_BASE_URL se sua API não estiver em https://api.stackspend.app.
• 401 Não autorizado — a chave é inválida ou foi revogada. Crie uma nova.
• Escopo obrigatório ausente — a chave é anterior a uma ferramenta. Crie uma nova chave para obter os escopos atuais.
• Plano Business obrigatório — o acesso à API faz parte do plano Business.

Acesso direto à API. O servidor MCP chama os mesmos endpoints da API pública disponíveis para todos os assinantes do plano Business. Você pode chamá-los diretamente para integrações personalizadas, scripts ou dashboards.