38 ferramentas sem devorar a janela de contexto: como projetamos o servidor MCP do KwaFlux

O essencial

• Cada ferramenta que um servidor MCP oferece é descrita para o modelo, e essa descrição ocupa um contexto que o modelo poderia usar para o seu pedido.
• Com as 38 ferramentas carregadas, a lista de ferramentas do KwaFlux tem 51.004 bytes, abaixo de um orçamento de 60.000 bytes. Carregando só o grupo principal, ela cai para 7.077 bytes.
• Os grupos de ferramentas permitem carregar só o que você usa: defina KWAFLUX_MCP_TOOLSETS, e os grupos não selecionados não chegam ao modelo.
• Os orçamentos são verificados por testes. Se uma mudança faz a lista de ferramentas, o grupo principal ou as instruções do servidor estourarem o orçamento, os testes falham.

Um servidor MCP que faz muita coisa tem um custo silencioso: o nome, a descrição e o schema de entrada de cada ferramenta são enviados ao modelo para que ele saiba que a ferramenta existe. Com poucas ferramentas, isso não faz diferença. Com 38, pode ocupar uma fatia considerável da janela de contexto antes mesmo de você digitar qualquer coisa.

Projetamos o servidor MCP do KwaFlux em torno desse custo. Os schemas são gerados, não escritos à mão; as ferramentas vêm em grupos que você pode desligar; os resultados são estruturados em vez de prolixos; e os tamanhos têm orçamentos que os testes fazem cumprir.

Neste guia, você vai ver de onde vem o custo de contexto de um servidor MCP, como o KwaFlux o mede e o limita, como carregar menos ferramentas e as decisões de design que deixam barato acompanhar tarefas de vídeo longas.

Conteúdo

1. Quanto contexto uma ferramenta MCP consome?
2. Os números do KwaFlux
3. Orçamentos que os testes fazem cumprir
4. Carregue só os grupos que você usa
5. Schemas gerados a partir da configuração do app
6. Resultados que não precisam ser lidos duas vezes
7. Tarefas longas: progresso e cancelamento, não polling
8. Prompts para fluxos de várias etapas
9. Perguntas frequentes

Quanto contexto uma ferramenta MCP consome?

O custo de contexto de uma ferramenta MCP é o tamanho da definição dela, ou seja, o nome, o título, a descrição e o JSON Schema de entradas e saídas, que o host repassa ao modelo a cada pedido de uma sessão.

Os hosts obtêm as definições com uma requisição tools/list. A maioria as inclui no contexto do modelo para que ele possa escolher uma ferramenta. A especificação do MCP pede que os servidores devolvam as ferramentas em uma ordem estável, em parte porque isso “melhora as taxas de acerto do cache de prompt do LLM quando as ferramentas são incluídas no contexto do modelo”, o que mostra como é comum elas irem parar lá.

Os números do KwaFlux

A lista completa tem cerca de 51 KB de JSON. Quantos tokens isso dá depende do tokenizador do modelo, mas é um custo fixo por sessão, pago antes do primeiro pedido. Só o grupo principal fica em cerca de um sétimo disso.

Orçamentos que os testes fazem cumprir

Uma meta de tamanho em um documento de design se perde com o tempo. Uma meta de tamanho em um teste, não.

O servidor MCP do KwaFlux tem um script de medição que roda junto com os testes. Ele monta a resposta real de tools/list, mede o tamanho em bytes, mede à parte o grupo principal e as instruções do servidor em caracteres, e falha se qualquer um deles passar do orçamento.

Isso muda o jeito de escrever ferramentas. Uma ferramenta nova precisa caber, então uma descrição longa é enxugada, uma explicação repetida vai para as instruções compartilhadas e um enum substitui um parágrafo explicando os valores válidos. O orçamento deixa uma folga, de cerca de 9 KB na lista completa, para recursos que ainda virão.

Carregue só os grupos que você usa

As 38 ferramentas do KwaFlux estão organizadas em grupos; a tabela mostra os principais. O grupo principal é carregado em qualquer configuração. Os outros você escolhe com a variável de ambiente KWAFLUX_MCP_TOOLSETS, e os grupos que você não escolhe nem chegam a ser registrados, então não ocupam contexto.

Por exemplo, se você só usa o assistente para converter e reparar arquivos, adicione a variável à entrada do KwaFlux na configuração MCP do seu host:

{
  "mcpServers": {
    "kwaflux": {
      "command": "<path to node>",
      "args": ["<path to kwaflux_mcp.mjs>"],
      "env": { "KWAFLUX_MCP_TOOLSETS": "convert,repair" }
    }
  }
}

Copie o command e os args da página Configurações › Agent (MCP) do KwaFlux em vez de digitá-los; o guia rápido mostra onde ficam. Cada host tem o próprio formato de configuração, então coloque o env onde o seu host espera.

Dica: comece com tudo carregado enquanto descobre o que o seu assistente consegue fazer e depois reduza aos grupos que você de fato usa. Uma lista de ferramentas menor também diminui a chance de o modelo escolher uma ferramenta que você não queria.

Schemas gerados a partir da configuração do app

A maior parte dos bytes de uma lista de ferramentas está nos schemas de entrada. Schemas escritos à mão tendem a crescer: um campo descrito em texto corrido, valores válidos listados na descrição e de novo no schema, observações sobre exceções.

Os schemas de aprimoramento do KwaFlux são gerados a partir do mesmo arquivo de configuração das telas do app. Cada ajuste vira um campo tipado com o intervalo real ou a lista real de opções, então o modelo vê "enum": [...] em vez de uma frase sobre quais valores são permitidos. As variantes para fotos saem do mesmo arquivo. O post sobre o plano de controle explica como um teste de divergência mantém as regras geradas alinhadas com o app.

Isso também mantém as ferramentas enxutas. Cada uma recebe os poucos campos que uma pessoa escolheria, e o KwaFlux monta o trabalho completo por conta própria. Uma ferramenta que aceitasse uma descrição de trabalho bruta precisaria de um schema para tudo o que o motor consegue fazer, o que seria maior e mais difícil de verificar.

Resultados que não precisam ser lidos duas vezes

Toda ferramenta do KwaFlux declara um outputSchema. Pela especificação do MCP, se uma ferramenta fornece um, “os servidores devem (MUST) fornecer resultados estruturados que estejam em conformidade com esse schema”, e os clientes “deveriam (SHOULD) validar os resultados estruturados com base nesse schema”.

Para o contexto, isso significa resultados em JSON compacto, com campos previsíveis: um ID de tarefa, um status, o nome de um arquivo de saída. O modelo não precisa ler um parágrafo para saber se algo deu certo, e um host pode verificar o resultado sem perguntar ao modelo. Os resultados também deixam de fora o que o modelo não precisa, assunto do post sobre caminhos e privacidade.

Tarefas longas: progresso e cancelamento, não polling

Tarefas de vídeo podem levar minutos. O jeito óbvio de um assistente acompanhar uma delas é perguntar “já terminou?” várias vezes seguidas, e cada verificação aumenta o contexto.

Em vez disso, o grupo principal do KwaFlux tem uma ferramenta de espera:

• Progresso. Quando o host inclui um progressToken, o KwaFlux envia notifications/progress enquanto a tarefa roda. Os hosts mostram isso como uma barra de progresso, fora do contexto do modelo.
• Cancelamento. Se você interromper o pedido no host, que envia notifications/cancelled, o KwaFlux para de esperar na hora. Depois, o assistente pode cancelar a própria tarefa, se você quiser.

Uma única chamada de espera substitui um loop de verificações de status, então uma exportação de dez minutos custa mais ou menos o mesmo contexto que uma de dez segundos.

Prompts para fluxos de várias etapas

Algumas tarefas precisam de várias ferramentas em sequência, como diagnosticar, depois reparar, depois aprimorar, depois exportar. Explicar essa ordem na descrição de cada ferramenta custaria bytes em todos os pedidos. Em vez disso, o KwaFlux traz essas sequências como quatro prompts MCP:

• reparar um vídeo danificado
• exportar para uma plataforma
• baixar e depois converter
• reparo de qualidade com IA

A especificação do MCP descreve os prompts como “controlados pelo usuário”, em geral oferecidos como comandos de barra. Eles não custam nada até você escolher um, e aí entregam ao modelo as etapas daquela tarefa. O post sobre os recursos mostra o que cada etapa faz.

Conclusão

Trate a lista de ferramentas como um orçamento, não como um catálogo: meça, imponha um teto em um teste e deixe as pessoas carregarem só os grupos de que precisam. Depois, mantenha cada chamada barata, com entradas tipadas geradas a partir da configuração real, resultados estruturados e progresso em vez de polling. É assim que o KwaFlux encaixa 38 ferramentas em um único servidor sem tirar espaço do seu pedido.

Carregue as ferramentas de que você precisa e deixe o resto de fora

O servidor MCP local do KwaFlux oferece a Codex, Claude, Cursor e outros apps MCP até 38 ferramentas em grupos que você pode desligar, com o grupo principal ativo em qualquer configuração. O processamento de IA roda na sua própria GPU e os seus arquivos de mídia não são enviados para processamento. Roda no Windows 10 (64 bits, versão 1809 ou mais recente), no Windows 11 e no macOS 12 ou mais recente em Apple Silicon. Importar arquivos e explorar o app não exigem conta. O login com um plano pago só é necessário para exportar, converter, reparar um arquivo ou baixar um arquivo de um link.

Baixar o KwaFlux · Ver planos