Ferramentas Disponíveis

Catálogo completo de tools expostas pelo MCP Server da GYRA+, agrupadas por domínio.

Resumo: esta página lista todas as tools do MCP Server da GYRA+, agrupadas por domínio (autenticação, relatórios, políticas, webhooks). Cada entrada descreve o que a tool faz, os parâmetros principais e um exemplo de prompt natural que costuma invocá-la.

Autenticação

authenticate

Troca clientId + clientSecret por um token de sessão (JWT). Geralmente não precisa ser chamada manualmente: o MCP autentica e renova o token automaticamente quando GYRA_CLIENT_ID e GYRA_CLIENT_SECRET estão configurados (ou via custom connector OAuth).

• Quando usa: agente que gerencia múltiplas organizações e precisa trocar de contexto on demand.
• Parâmetros: clientId, clientSecret.
• Retorno: { accessToken, expiresIn }.

Relatórios

create_report

Cria uma nova análise para um CPF ou CNPJ.

• Parâmetros: document, policyId, opcional amount.
• Retorno: objeto Report com id e status inicial (PROCESSING).
• Prompt típico: “roda uma análise no CNPJ 43.591.367/0001-30 com a política Capital de Giro”.

get_report

Consulta o detalhe de um relatório existente pelo id.

• Parâmetros: reportId.
• Retorno: objeto Report completo.
• Prompt típico: “mostra o resultado da análise 6612a7f3…”.

list_reports

Lista relatórios da organização com filtros.

• Parâmetros: opcionais status, document, policyId, from, to, limit, offset.
• Prompt típico: “quais foram as 10 últimas análises?”.

count_reports

Conta quantos relatórios existem que atendem filtros específicos.

• Parâmetros: mesmos filtros de list_reports.
• Prompt típico: “quantas análises foram negadas este mês?”.

get_section

Retorna uma seção específica de um relatório.

• Parâmetros: reportId, sectionId.
• Prompt típico: “me traz a seção de processos judiciais desse relatório”.

get_report_section_by_type

Atalho para pegar seção por tipo, sem precisar saber o sectionId.

• Parâmetros: reportId, sectionType (ex: "LAWSUITS", "BUREAU", "SCR").
• Prompt típico: “qual o score do bureau nesse relatório?”.

analyze_report

Registra uma análise manual de um relatório: o usuário submete uma decisão (aprovado/negado) com justificativa, sobrescrevendo ou complementando o resultado automático da política.

• Parâmetros: reportId, approved (boolean), commentary (motivo da decisão).
• Quando usa: analista de crédito precisa registrar decisão manual (ex.: “aprovado por relacionamento comercial”, “negado por política interna”).
• Prompt típico: “marca o relatório X como aprovado, justificativa: cliente histórico com bom relacionamento”.

re_analyze_report

Refaz uma análise manual já registrada em um relatório. Só pode ser usada quando já existe uma análise manual prévia e o usuário tem permissão para revisar.

• Parâmetros: reportId, approved, commentary.
• Quando usa: revisão de decisão manual anterior (ex.: nova informação chegou e o analista quer alterar o parecer já dado).
• Prompt típico: “reanalisa manualmente esse relatório, mudei minha decisão para negado”.

export_report_sync

Exporta o relatório em PDF, XLS ou ambos e retorna um link com validade de 7 dias.

• Parâmetros: reportId, exportFormat ("pdf", "excel" ou "both").
• Prompt típico: “gera um PDF desse relatório” ou “me manda a planilha do relatório”.

Políticas

list_policies

Lista as políticas de crédito da organização.

• Parâmetros: opcionais documentType ("PF" / "PJ"), enabled.
• Prompt típico: “quais políticas PJ estão ativas?”.

Webhooks

create_webhook

Cria um webhook para receber notificações de eventos. Um webhook por tipo — registre vários se precisa escutar mais de um.

• Parâmetros: type (REPORT, REPORT_FINISHED, REPORT_STATUS, REPORT_EXPORTED, CREDIT_POLICY, OPERATION), url, apiKey (opcional, enviado como header api-key nas chamadas).
• Prompt típico: “configura webhook REPORT_FINISHED apontando para https://meu-backend/gyra”.

find_webhooks

Lista webhooks configurados.

• Parâmetros: opcionais webhookId, type.
• Prompt típico: “quais webhooks eu tenho configurados?”.

delete_webhook

Remove um webhook.

• Parâmetros: webhookId.
• Prompt típico: “remove o webhook antigo que não está sendo usado”.

Exemplos encadeados

O poder do MCP aparece quando o agente encadeia tools sem você precisar dizer qual chamar:

Exemplo 1, análise completa por conversa

Você: “roda uma análise no 43591367000130 com a política padrão PJ e me diz por que foi aprovada ou negada.”

1. Agente chama list_policies filtrando por PJ para achar a política padrão.
2. Agente chama create_report com document e policyId.
3. Agente faz polling em get_report até status COMPLETED.
4. Agente chama get_report_section_by_type para pegar o breakdown.
5. Agente responde em linguagem natural com a conclusão.

Exemplo 2, auditoria semanal

Você: “quantas análises negadas tivemos esta semana e qual a regra mais frequente de bloqueio?”

1. Agente chama count_reports com status: "DENIED" e intervalo de datas.
2. Agente chama list_reports com o mesmo filtro.
3. Agente consulta breakdown de cada relatório via get_report_section_by_type.
4. Agente agrega e responde.

Limitações

• Tools disponíveis refletem o escopo contratado pela organização. Features não contratadas retornam erro claro.
• Rate limit aplicável: mesmas regras da API REST (100 req/min padrão). O cliente MCP retransmite 429 e o modelo espera.
• Payloads grandes: relatórios COMPLETO+ podem exceder o limite de contexto do modelo. Use get_report_section_by_type em vez de get_report para buscar só o que precisa.

Perguntas frequentes

Posso criar tools customizadas?

Por enquanto o catálogo é fechado. Se você precisa de tool específica, fale com o suporte. Se precisa de tool composta, deixe o modelo encadear as existentes (costuma ser suficiente).

As tools têm descrição em português ou inglês?

Os schemas (nomes, parâmetros) estão em inglês para alinhar ao padrão MCP. As descrições funcionais estão em português para que modelos em PT-BR escolham corretamente.

Como vejo o que o modelo chamou em background?

Todo cliente MCP sério (Claude Desktop, Cursor) mostra as tool calls na UI. Além disso, toda chamada fica no log de auditoria do toolbox.

Próximos passos

Casos de uso

Conversas práticas com exemplos reais.

Troubleshooting

Quando uma tool não é chamada.

Instalação

Voltar e configurar o cliente.

API REST

Acesso direto sem MCP.