Costory

Costory FinOps MCP: habilidades de agente e plugin

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 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	Descubra dimensões, dashboards, métricas e a maneira correta 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	Defina eixos de custo personalizados com regras CEL ordenadas, visualize e publique
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 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
query	Investigação de custo, uso, métrica, fórmula e orçamento. Explorador apenas entre períodos; repassa "o que mudou" para reports Explain
virtual-dimensions	Criar, editar, visualizar e publicar eixos de custo personalizados com regras CEL ordenadas
dashboards	Criar ou estender 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 dashboards de orçamento versus real, alertas de pico de EC2, divisões de produção versus P&D, cobertura de custos não marcados, gastos com 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/
    query/SKILL.md
    virtual-dimensions/SKILL.md
    dashboards/SKILL.md
    reports/SKILL.md
    recipes/SKILL.md  + recipe library

Servindo habilidades via MCP (get_skill)

skills.json mapeia cada MCP skillId para um caminho 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.