Camada de Integração REST-First da Corsair: Por que Apenas MCP Não é Suficiente para Ferramentas de Agentes em Produção

A maioria das ferramentas de integração de agentes o prende a um único contexto. Você conecta servidores MCP para seu LLM, e depois reconstrói os mesmos fluxos de OAuth e adaptadores de API quando seu trabalho cron de backend precisa do Slack ou quando seu painel de controle de cliente precisa do Google Calendar. A Corsair (10.937 estrelas, tendência #2 no GitHub TypeScript) segue um caminho diferente: uma plataforma de integração REST-first que atende agentes, serviços de backend e painéis de controle voltados para o usuário a partir da mesma camada de adaptador.

Isso é importante porque sistemas de agentes em produção raramente vivem em isolamento. A mesma integração que alimenta a chamada de ferramenta de um agente também precisa ser executada em um trabalho agendado, aparecer em um painel de administração multi-inquilino ou lidar com callbacks de webhook quando um serviço de terceiros envia atualizações. Ferramentas apenas MCP forçam você a manter encanamentos paralelos para cada contexto.

O Armadilha Apenas MCP

O MCP (Modelo de Protocolo de Contexto) é excelente para comunicação entre agente e ferramenta. Ele define uma maneira padrão para LLMs descobrirem e invocarem funções. Mas os servidores MCP são sem estado, com escopo de sessão e projetados para ciclos de solicitação-resposta síncronos. Eles não lidam com:

• Atualização de token OAuth em sessões de longa duração
• Ingestão de webhook de serviços de terceiros
• Armazenamento de credenciais multi-inquilino
• Agendamento de trabalhos de backend que precisam do mesmo acesso à API
• Painéis de controle voltados para o usuário onde os clientes conectam suas próprias contas

Se você construir apenas com MCP, acabará escrevendo manipuladores de OAuth separados, clientes de API separados e armazenamentos de credenciais separados para cada contexto não-agente. A Corsair resolve isso colocando uma API REST na frente da camada de integração. A mesma sintaxe unificada funciona, seja o chamador um LLM, um trabalho cron ou um componente React.

Arquitetura: API REST como o Substrato de Integração

O núcleo da Corsair é uma API REST que normaliza integrações de terceiros. Cada integração (Slack, Google Calendar, GitHub, etc.) expõe uma interface consistente:

• Autenticação: Fluxos de OAuth, atualização de token e armazenamento de credenciais gerenciados pela plataforma
• Sintaxe unificada: Mesma forma de solicitação entre provedores, independentemente das peculiaridades da API subjacente
• Manipulação de webhook: Eventos de entrada de serviços de terceiros roteados para sua aplicação
• Suporte multi-inquilino: Credenciais com escopo de usuário, não contas de serviço globais

O fluxo é assim:

1. Usuário conecta conta: A dança do OAuth acontece uma vez, credenciais armazenadas na Corsair
2. Agente faz chamada de ferramenta: LLM invoca um endpoint REST da Corsair com o contexto do usuário
3. Corsair traduz: A plataforma mapeia a solicitação para a API do provedor, lida com a autenticação, retorna a resposta normalizada
4. Mesmo endpoint para backend: Seu trabalho cron atinge o mesmo endpoint REST com a mesma sintaxe
5. Mesmo endpoint para painel: Seu frontend chama o mesmo endpoint para exibir dados do usuário

Isso elimina o problema de duplicação de adaptadores. Você escreve a lógica de integração uma vez, e ela funciona em todos os contextos.

Formas de Implantação: Auto-Hospedado vs. Hub Gerenciado

A Corsair oferece dois modelos de implantação:

A auto-hospedagem oferece controle completo, mas requer a execução de um armazenamento de credenciais, gerenciamento de temporizadores de atualização de token e exposição de endpoints de webhook com segurança adequada. A opção de Hub gerenciado transfere a gestão do estado do OAuth, mantendo seus dados de usuário em sua aplicação. Webhooks chegam à infraestrutura da Corsair, são validados e, em seguida, encaminhados para suas URLs de callback.

Para sistemas de agentes em produção, o Hub gerenciado reduz a área de superfície para bugs de expiração de token OAuth. A auto-hospedagem faz sentido se você precisar de implantações isoladas ou tiver requisitos rigorosos de residência de dados.

Gerenciamento de Estado: Markdown + Git para Camada de Conhecimento

A Corsair usa arquivos markdown em um repositório git para sua camada de conhecimento em vez de um banco de dados vetorial ou armazenamento em grafo. Esta é uma escolha opinativa com trade-offs específicos:

Por que markdown + git:

• Diferença: Cada mudança no esquema de integração é um commit
• Auditoria: Histórico completo de quem mudou o que e quando
• Portabilidade: Sem migração de banco de dados ao mover ambientes
• Amigável para desenvolvedores: Engenheiros podem PR atualizações de integração como código

Trade-offs:

• Sem busca semântica: Você não pode consultar "encontrar todas as integrações que suportam eventos de calendário" sem grep
• Sem indexação em tempo real: Mudanças requerem um git pull, não uma consulta de banco de dados
• Limites de escala: Funciona bem para centenas de integrações, fica complicado em milhares
• Sem permissões granulares: Controle de acesso a nível de git, não a nível de linha

Isso funciona bem para equipes que tratam integrações como infraestrutura como código. Isso quebra se você precisar de esquemas de integração dinâmicos gerados pelo usuário ou busca em tempo real através de metadados de integração.

Fluxo de Chamada de Ferramenta: Agente para API de Terceiros

Veja como uma chamada de ferramenta de agente flui através da Corsair:

// O agente invoca uma integração da Corsair
const response = await fetch('https://api.corsair.dev/v1/integrations/slack/send-message', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${corsairApiKey}`,
    'X-User-Context': userId  // Pesquisa de credenciais multi-inquilino
  },
  body: JSON.stringify({
    channel: '#general',
    text: 'Mensagem gerada pelo agente'
  })
});

// A Corsair lida com:
// 1. Pesquisa de credenciais do usuário (token OAuth para este userId + Slack)
// 2. Atualização de token se expirado
// 3. Tradução para o formato da API do Slack
// 4. Limitação de taxa