Servidor MCP

O fg-tracker-mcp (0.12.0) é um servidor MCP que roda na sua máquina, aberto pelo próprio cliente de IA via stdio. Ele conversa com a API do FG Tracker usando um token pessoal seu, e o agente passa a consultar traces, issues e logs, registrar releases e criar monitores com as permissões que você deu.

Requisitos

• Node.js 20 ou mais novo com npx no PATH do cliente de IA.
• Uma conta com e-mail confirmado e ao menos um projeto (ou permissão para criar um).
• Um token pessoal fgt_…. A chave do projeto (stk_ ou fgsk_) não substitui o token.

1. Crie o token

No painel, abra Conectar → Usar MCP → Gerar token para o MCP (ou Conta → Tokens de acesso → Novo token) e mantenha o modelo Agente MCP (recomendado). Escolha a validade e os projetos, clique em Criar token e copie o valor: ele aparece uma vez só. O diálogo Token criado já mostra a configuração pronta para copiar.

Para um agente que só investiga, use o modelo Somente leitura. Exclusões, infraestrutura AWS e testes de carga exigem o modelo Personalizado. Detalhes em Permissões do token.

2. Configure o cliente

Claude Code

claude mcp add fg-tracker \
  -e FG_TRACKER_URL=https://tracker-api.fortground.com.br \
  -e FG_TRACKER_TOKEN=fgt_<seu_token> \
  -- npx -y fg-tracker-mcp@0.12.0

Codex CLI

[mcp_servers.fg-tracker]
command = "npx"
args = ["-y", "fg-tracker-mcp@0.12.0"]

[mcp_servers.fg-tracker.env]
FG_TRACKER_URL = "https://tracker-api.fortground.com.br"
FG_TRACKER_TOKEN = "fgt_<seu_token>"

Cursor, Windsurf e Claude Desktop

Esses clientes usam o mesmo bloco JSON, cada um no seu arquivo:

• Cursor: .cursor/mcp.json no projeto ou ~/.cursor/mcp.json.
• Windsurf: ~/.codeium/windsurf/mcp_config.json.
• Claude Desktop: Configurações → Desenvolvedor → Editar configuração (claude_desktop_config.json); reinicie o app.

{
  "mcpServers": {
    "fg-tracker": {
      "command": "npx",
      "args": ["-y", "fg-tracker-mcp@0.12.0"],
      "env": {
        "FG_TRACKER_URL": "https://tracker-api.fortground.com.br",
        "FG_TRACKER_TOKEN": "fgt_<seu_token>"
      }
    }
  }
}

A versão fixa (@0.12.0) evita que uma atualização mude as ferramentas sem você saber; troque o número para atualizar.

3. Teste

Para conferir que o pacote abre na sua máquina:

npx -y fg-tracker-mcp@0.12.0 --version

Depois, no cliente, peça ao agente: “use tracker_status e me diga quais projetos você enxerga”. A resposta mostra a URL da API, o tipo de credencial (token pessoal), a validade, as permissões e os projetos. Com um projeto que já recebe dados: “liste os traces da última hora do projeto Checkout API”.

Variáveis de ambiente

Ferramentas por objetivo

O servidor só registra as ferramentas que o seu token permite. Com o modelo Agente MCP e FG_TRACKER_LEGACY_TOOL_NAMES=0, são 47 ferramentas; com Somente leitura, 34. Também há ferramentas de infraestrutura AWS (infra_*) e de teste de carga (loadtest_*), que exigem permissões próprias e não são tratadas aqui.

Prompts prontos: instrument-project (instrumentar um projeto), investigar-regressao-p95, investigar-query-lenta, investigar-job-atrasado, investigar-erro-distribuido e confirmar-correcao. Janelas: range (15m a 30d) ou from/to ISO 8601, até 31 dias.

Escrita e confirmação

• Ferramentas que excluem (tracker_delete_monitor, tracker_delete_alert_rule, tracker_delete_sourcemaps e as de infraestrutura e teste de carga) exigem o parâmetro confirm com o nome ou slug exato do recurso. O servidor lê o recurso na API antes e recusa sem excluir nada se o valor não bater.
• tracker_update_allowed_origins substitui a lista inteira de domínios: peça ao agente para listar antes.
• Para um agente que não deve alterar nada, use um token Somente leitura ou FG_TRACKER_READ_ONLY=1.

Permissões e reinício

As permissões do token são lidas uma vez, quando o cliente abre o servidor (GET /v1/auth/me). Depois de editar o token, trocar de projeto ou de papel, reinicie o cliente de IA para a lista de ferramentas mudar; tracker_status avisa quando as permissões atuais diferem das do início. Se a API não responder na abertura, o servidor registra só as ferramentas de leitura.

Chaves de ingestão no MCP

A variável FG_TRACKER_API_KEY ainda existe por compatibilidade: sem FG_TRACKER_TOKEN, só duas ferramentas de infraestrutura e teste de carga a usam, e as demais respondem 401. Não a use como alternativa ao token. Com token definido, ela é ignorada.

Erros e limites

• Listas param em FG_TRACKER_MAX_ITEMS; listas internas, em 25 itens (com …Omitted). tracker_get_trace pagina os spans de 80 em 80.
• O token nunca aparece nas respostas, e as mensagens de erro mascaram fgt_… e stk_…. A chave pública aparece de propósito em tracker_create_project e tracker_list_projects (esta só para owner e admin com ingest_key:read).