Costory

Costory FinOps MCP: habilidades e plugin para agentes

O Costory FinOps MCP é um servidor Model Context Protocol hospedado que permite que Claude, Cursor, VS Code, Codex ou Dust respondam perguntas sobre seus gastos em nuvem e IA.

Alimentar um prompt com linhas brutas de faturamento da AWS ou GCP não funciona. A Costory atua como uma camada de contexto: ela normaliza o faturamento de AWS, GCP, Azure, Snowflake, Datadog, OpenAI e Anthropic em um único esquema, aloca custos compartilhados e não marcados com base em métricas reais de uso e correlaciona gastos com eventos de deploy e incidentes. O assistente então chama ferramentas estruturadas com base em dados que já estão alocados e explicados.

Este repositório contém as habilidades de agente que ficam acima dessas ferramentas: os fluxos de trabalho que transformam "por que o custo de produção saltou na semana passada" na sequência correta de chamadas de ferramentas.

• Documentação completa do MCP: docs.costory.io/features/mcp
• Endpoint: https://app-api.costory.io/mcp
• Autenticação: OAuth, sem credenciais IAM, sem Docker, sem servidor local

Conecte o MCP

Você precisa de um workspace Costory com dados de faturamento conectados. Um teste de 15 dias está disponível.

Claude Desktop / Claude Code / Cursor / VS Code: adicione um conector personalizado apontando para https://app-api.costory.io/mcp e conclua o login OAuth na janela do navegador que abrir. Guias passo a passo por cliente com capturas de tela estão na documentação do MCP.

Este repositório inclui um .mcp.json que você pode copiar:

{
  "mcpServers": {
    "costory": {
      "type": "http",
      "url": "https://app-api.costory.io/mcp",
      "oauth": { "callbackPort": 8080 }
    }
  }
}

Para clientes sem suporte nativo a MCP remoto, faça o proxy com mcp-remote:

{
  "mcpServers": {
    "costory": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app-api.costory.io/mcp"]
    }
  }
}

Referência das ferramentas MCP

O servidor expõe ferramentas em cinco grupos. Nomes e payloads são versionados; a referência da API é a fonte da verdade.

Grupo	Ferramentas	O que fazem
Orientação	get_context, search, get, suggest_groupby, suggest_usage_metrics, suggest_actions	Descobrir dimensões, dashboards, métricas e a melhor forma de segmentar uma pergunta
Consulta	query, list_metrics, list_virtual_dimensions	Consultas de custo, uso, métrica, fórmula e orçamento com comparação entre períodos
Alocação	create_virtual_dimension_draft, update_virtual_dimension_draft, preview_virtual_dimension_draft, publish_virtual_dimension, virtual_dimension_overlap_matrix	Definir eixos de custo personalizados com regras CEL ordenadas, visualizar e depois publicar
Relatórios	create_report, update_report, preview_report_widget, run_report_now, create_dashboard, update_dashboard	Relatórios agendados por Slack, Teams e e-mail, além de dashboards criados a partir do chat
Alertas e eventos	create_alert, preview_alert, list_alerts, create_event, update_event	Alertas de custo e orçamento, e anotações de eventos para correlação

As ferramentas de escrita atuam apenas dentro do seu workspace Costory. O escopo das consultas segue a função do usuário que está chamando no workspace.

Habilidades FinOps

As habilidades são a camada de fluxo de trabalho: cada uma codifica como sequenciar as ferramentas acima para uma classe de pergunta, para que o assistente não precise redescobrir isso.

MCP skillId	Use quando
bigquery	Ressalvas do warehouse BigQuery (on-demand vs slots, físico vs lógico, labels) além do template de dashboard [BigQuery]
cost-change-investigation	Explicar uma mudança de custo com evidências de contribuição, tempo, uso, métrica, evento, alerta e terminologia
query	Investigação de custo, uso, métrica, fórmula e orçamento. Explorador apenas período a período; repassa "o que mudou" para reports Explicar
virtual-dimensions	Criar, editar, visualizar e publicar eixos de custo personalizados com regras CEL ordenadas
dashboards	Criar ou ampliar dashboards com herança de widgets com foco em contexto e geração de visão geral
reports	Relatórios agendados por Slack, Teams e e-mail, e DIGEST com visualização prévia para explicar o custo do último mês
recipes	Designs de rastreamento prontos, alinhados a um resultado, e depois repassados às habilidades acima para construção

As receitas atualmente cobrem roteamento de warehouse BigQuery, CUDs baseados em gastos da GCP, dashboards de orçamento vs. real, alertas de pico em EC2, divisões produção vs. P&D, cobertura de itens não marcados, gastos em marketplace, créditos de provedor, custo por namespace, análises detalhadas de computação e explicação de mudanças entre períodos. Veja plugins/costory/skills/recipes/.

Instalar como plugin

# Claude Code
claude plugin marketplace add costory-io/costory-finops-mcp-skills
claude plugin install costory@costory

# Codex
codex plugin marketplace add costory-io/costory-finops-mcp-skills
codex plugin add costory@costory

Estrutura

.mcp.json                              ← ready-to-copy MCP client config
skills.json                            ← MCP skillId -> SKILL.md path
.claude-plugin/marketplace.json
plugins/costory/
  .claude-plugin/plugin.json
  skills/
    bigquery/SKILL.md
    cost-change-investigation/SKILL.md
    query/SKILL.md
    virtual-dimensions/SKILL.md
    dashboards/SKILL.md
    reports/SKILL.md
    recipes/SKILL.md  + recipe library

Disponibilizando habilidades via MCP (get_skill)

skills.json mapeia cada MCP skillId para um caminho de SKILL.md. Ao integrar o costory-app, carregue o arquivo deste repositório (ou de uma versão fixada), remova o frontmatter YAML opcional e retorne o corpo em markdown.

{
  "skillId": "dashboards",
  "path": "plugins/costory/skills/dashboards/SKILL.md"
}

Autoria

Veja AGENTS.md para regras de estrutura, incrementos de versão e validação. Use SKILL_TEMPLATE.md ao adicionar uma habilidade.

Licença

Apache-2.0, veja LICENSE.