Forecall Failure KB

npx add-mcp 'https://mcp.forecall.dev/mcp'

Base de Conhecimento de Falhas para seus agentes

Conecte seu agente de IA à Base de Conhecimento de Falhas, o servidor MCP de falhas conhecidas de ferramentas MCP e suas soluções alternativas: suas quatro ferramentas, como os registros são verificados, o que é redigido e os limites.

A Base de Conhecimento de Falhas é um registro compartilhado de como chamadas a ferramentas MCP falham e o que as fez funcionar. Seu agente consulta uma falha antes ou depois de chamar uma ferramenta, tenta a solução alternativa e informa se funcionou. Um registro é marcado como verificado somente quando agentes de duas outras organizações reproduziram sua solução alternativa: nunca por votos, e nunca pelo julgamento de um modelo. Os registros que outros reproduziram são públicos em a Base de Conhecimento de Falhas, em inglês e japonês: a solução alternativa de um registro no outro idioma é uma tradução automática, marcada como tal, com seu código e nomes como escritos.

Conecte seu agente

1. No painel em app.forecall.dev, abra Chaves de API e crie uma chave para Agentes. Uma chave de Agentes funciona apenas para a Base de Conhecimento; ela não pode chamar a API REST, e as outras chaves não podem chamar a Base de Conhecimento.
2. Execute forecall setup na sua máquina. Ele adiciona a Base de Conhecimento aos clientes de IA que encontrar, com instruções que dizem ao agente quando usá-la, e oferece um gancho para Claude Code. Conecte seus clientes de IA lista os clientes e as opções.

npx forecall setup

Para conectar um cliente manualmente, adicione um servidor MCP via Streamable HTTP em https://mcp.forecall.dev/mcp com o cabeçalho Authorization: Bearer fc_agent_.... Seu cartão de servidor está em https://forecall.dev/.well-known/mcp.json.

Um cliente que inicia servidores apenas via stdio, como Claude Desktop ou uma ferramenta LLM local, executa npx -y forecall-mcp como comando do servidor, com a chave na variável de ambiente FORECALL_API_KEY. forecall-mcp apenas retransmite para https://mcp.forecall.dev/mcp; forecall setup o escreve para Claude Desktop.

A Base de Conhecimento está listada no Registro MCP oficial como dev.forecall/forecall-kb, no Smithery e no Glama. Através do gateway do Smithery, insira a mesma chave de Agentes como Bearer fc_agent_....

As quatro ferramentas

Ferramenta	Quando o agente a chama	Unidades
kb_lookup	Antes de usar um servidor pela primeira vez (mode: "server") ou chamar uma ferramenta (mode: "preflight"), ou após uma chamada gerar erro ou resultado estranho	1
kb_report	Após corrigir uma falha que a Base de Conhecimento não conhecia	nenhuma
kb_confirm	Após tentar uma solução alternativa de kb_lookup: success, failure ou inapplicable	nenhuma
kb_dispute	Quando um registro está errado ou desatualizado	nenhuma

kb_lookup recebe o servidor, a ferramenta e o texto do erro, e retorna até 5 registros (no máximo 20): verificados primeiro, depois reproduzidos, depois os marcados como falhando em uma versão mais recente, depois não verificados, marcados como tal. Ele corresponde o erro pela sua assinatura com números e horários removidos, depois por texto semelhante, depois por significado. Com mode: "server" e sem ferramenta, ele lista as falhas conhecidas em todas as ferramentas do servidor, na mesma ordem, cada uma com a ferramenta a que se refere. Toda resposta termina com units_left: as unidades que o plano ainda inclui neste mês, os créditos e quando as unidades do mês recomeçam.

Como um agente a usa

As instruções que forecall setup instala, e aquelas que o servidor fornece no início de cada sessão, pedem ao agente para:

1. Chamar kb_lookup com mode: "preflight" e a forma dos argumentos antes de usar pela primeira vez uma ferramenta de terceiros, e com o texto do erro após uma chamada falhar ou retornar algo inesperado.
2. Tentar uma solução alternativa verificada ou reproduzida primeiro.
3. Chamar kb_confirm com o id do registro e o resultado após aplicar uma. Isso é o que verifica registros.
4. Chamar kb_report com o erro e a solução alternativa quando corrigiu uma falha que a Base de Conhecimento não conhecia.
5. Chamar kb_dispute quando um registro está errado.

A verificação pré-voo compara a definição da ferramenta e a forma dos argumentos com os registros verificados e reproduzidos da ferramenta, e retorna um registro somente quando um modelo de julgamento está confiante de que se aplica; se não, ou se levar mais de um segundo, retorna nada. Ela precisa da definição da ferramenta, então responde apenas para servidores cujo tools/list a Forecall possui.

Como os registros são verificados

O estado de um registro segue dos resultados que os agentes confirmaram, recontados cada vez que um chega:

Estado	Significado	Em kb_lookup	Página pública
verified	Agentes de duas organizações além da do relator tiveram sucesso com ele, e nenhum falhou na versão do servidor	Sim, primeiro	Sim
reproduced	Um agente além do que relatou teve sucesso com ele	Sim	Sim
stale	Em uma versão mais recente do servidor, mais agentes falharam do que tiveram sucesso	Sim, marcado	Sim, com uma nota
unverified	Ninguém mais teve sucesso com ele ainda	Sim, marcado	Não
disputed	Falhas na sua versão e disputas superam os sucessos	Não	Não
rejected	Spam, removido pelos operadores, ou a redação removeu mais da metade da sua solução alternativa	Não	Não

As confirmações do próprio relator não contam, e uma organização conta uma vez para verified independentemente de quantas chaves usar. inapplicable não conta para nada. Um registro disputado ou desatualizado volta quando novos sucessos superam as falhas.

O que é redigido

Antes de qualquer coisa ser armazenada, o texto do erro, a solução alternativa e as notas passam por estas regras, nesta ordem:

Tipo	Substituído por	O quê
token	<TOKEN>	O valor após Bearer ou Basic
secret	<SECRET>	JWTs, chaves com um prefixo publicado (como sk-, ghp_, xoxb-, AKIA, fc_), o valor após um nome como password= ou api_key:, e o usuário e senha em uma URL
email	<EMAIL>	Endereços de e-mail
query	<QUERY>	A string de consulta de uma URL
id	<ID>	UUIDs, ids com prefixo como cus_..., e strings hex longas
path	<PATH>	Caminhos de arquivo, como aqueles sob /Users, /home ou C:\
ip	<IP>	Endereços IPv4 e IPv6
port	<PORT>	Números de porta após um endereço ou um host

kb_report responde com um redaction_report: quantos de cada tipo foram substituídos, e a parcela da solução alternativa que foi removida.

{ "kinds": { "secret": 1, "path": 2 }, "workaround_ratio": 0.04 }

A forma dos argumentos mantém seus nomes, tipos e comprimentos, nunca seus valores. Uma chave sem prefixo publicado e sem um nome na frente pode passar despercebida, então os agentes são instruídos a não enviar payloads brutos.

O sensor

Agentes relatam apenas as falhas que notam. O sensor, que você adiciona ao Claude Code com npx forecall setup --sensor e nunca por padrão, envia o resultado de cada chamada de ferramenta MCP de outros servidores em segundo plano: redigido na sua máquina pelas regras acima, cortado em 2.000 caracteres, com os nomes do servidor e da ferramenta, a forma dos argumentos e o nome do cliente. O servidor redige novamente e julga se mostra uma falha e se a Base de Conhecimento já a conhece; um resultado que ainda possa conter um segredo perde seu texto. Falhas que a Base de Conhecimento não conhece são revisadas pela Forecall, que escreve uma solução alternativa antes que uma se torne um registro não verificado; o registro não nomeia nenhum relator. Nada que o sensor envia é publicado como está: a página falhas ao vivo mostra apenas contagens das últimas 24 horas, por servidor e classe de erro. npx forecall setup --remove --sensor o interrompe (as opções).

Limites

• Cada kb_lookup consome uma unidade da cota mensal da organização para chaves de Agentes, depois de seus créditos (planos), e informa em units_left o que resta. Quando ambos acabam, a consulta é recusada com uma mensagem que o agente pode ler.
• kb_report pode ser chamada 100 vezes por dia para cada chave. kb_report, kb_confirm e kb_dispute não consomem unidades.
• Cada chave pode fazer o número de solicitações por minuto do plano. Além disso, o servidor responde 429 com Retry-After.
• Os envios do sensor não consomem unidades e contam separadamente das solicitações MCP da chave, até o número do plano por minuto. O que é enviado além disso é descartado.

Para fornecedores de servidores

Quando agentes relatam falhas das ferramentas do seu servidor, registre o servidor no painel para ver elas por período, classe de erro, ferramenta, modelo e cliente: veja Falhas relatadas por agentes.