connector-engine

Um gateway entre apps de IA e servidores de ferramentas que decide, por app e por função, o que roda, o que espera uma pessoa e o que é recusado.

Goversatile.shcódigo disponível (GPL-3.0-or-later)Linguagem GoLicença GPL-3.0-or-laterSuperfícies MCP, HTTP, gRPCArmazenamento Postgres, SQLite, memóriagithub.com/versatile-sh/connector-engine
mcprestgrpc?

Visão geral

O connector-engine fica entre seus apps de IA e os servidores de ferramentas que eles chamam (MCP, REST, gRPC). Um app fala com um único endpoint, /mcp. O motor decide, para cada função, se ela está desligada, ligada ou se precisa que uma pessoa a aprove antes.

Cada definição de função é fixada por um hash RFC 8785. Uma ferramenta que muda depois da instalação, ou uma nova, fica em quarentena até uma pessoa aceitá-la, então um servidor não consegue ampliar o que um agente pode fazer sem aviso.

Ele vem em dois perfis: person, um console local em 127.0.0.1 que atua como servidor OAuth 2.1 para todos os apps de IA da máquina, e headless, um motor sem console que confia no seu emissor OIDC e expõe uma API de operador e CloudEvents.

ItemValor
Console e endpoint de agente padrãohttp://127.0.0.1:7465 e /mcp
Listeners padrão do motorserver.listen :8080, server.grpcListen :9090
Janela de espera de um askapproval.holdWindow, 20s
Expiração da aprovaçãoapproval.timeout, 10m
Agenda de re-listagempinning.relistMin 30s a pinning.relistMax 5m

Instalar e rodar

Pré-requisitos: Docker e mise para o caminho que funciona hoje. Os instaladores sem Docker e a imagem de release estão documentados como disponíveis após a v0.1.0.

termina com: console: http://127.0.0.1:7465 agent endpoint: http://127.0.0.1:7465/mcpsh
git clone https://github.com/versatile-sh/connector-engine
cd connector-engine
mise run up
após a v0.1.0; os instaladores verificam o SHA-256 de cada downloadsh
curl -fsSL https://raw.githubusercontent.com/versatile-sh/connector-engine/main/scripts/install.sh | sh
vsh up --open

Conecte um app e depois use a mesma API pelo terminal com o vsh:

sh
claude mcp add --transport http versatile http://127.0.0.1:7465/mcp
codex mcp add versatile --url http://127.0.0.1:7465/mcp

vsh login
vsh connectors import --mcp https://mcp.example.com/mcp
vsh access github --kind read on
vsh approvals

O motor lê dois arquivos YAML. Chaves desconhecidas são erros e uma chave ausente mantém seu valor padrão. Segredos nunca são escritos neles: uma chave terminada em Ref aceita env:NAME ou file:/path.

ArquivoFlagAmbiente
connector-engine.yaml--configCN_CONFIG
adapters.yaml--adaptersCN_ADAPTERS_FILE
ChavePadrãoSignificado
modeproductiondev relaxa as verificações de produção
server.operatorListen"" (off)a API de operador
auth.issuers[]emissores OIDC confiáveis
auth.agentTokenMaxLifetime1hmaior duração de token de agente aceita
permission.defaultModedenyuma função sem concessão
runtime.allowPrivateHostsfalsedeixa os conectores alcançarem endereços privados
gateway.skillsofftools ou tools+prompts serve skills
retention.*0s (keep)poda eventos, chaves, auditoria e chamadas a cada retention.every
valida a seleção de adaptadores do jeito que o boot faz; imprime: adapters oksh
connector-engine --config connector-engine.yaml --adapters adapters.yaml adapters check

Nunca publique a porta do console diretamente. Em um servidor, use um túnel SSH ou um proxy TLS com CONSOLE_PUBLIC_URL definido. O primeiro visitante de um console novo vira o Owner; CONSOLE_SETUP_TOKEN faz a primeira tela pedir um segredo.

Arquitetura

mcpgrpcportcoreinstorerestkeys
Os adaptadores dos dois lados tocam o núcleo puro apenas pelo anel de portas.

Portas e adaptadores. As dependências apontam para dentro: os adaptadores importam port, o núcleo importa apenas port, e app/ liga tudo. scripts/check-layering.sh garante que nada no núcleo importe selfhosted/.

CamadaPacotesRegra
Portasport/tipos neutros, interfaces, códigos de erro e de motivo; sem tipos de infraestrutura
Núcleocore/*funções puras sobre tipos de port: sem I/O, sem relógio, sem globais
Casos de usoservice/uma transação do store por mutação; service/worker roda timers e varreduras
Entradagateway/, server/traduzem MCP, HTTP, gRPC e MCP de gerenciamento em casos de uso
Saídastore/, runtime/, source/, secrets/, auth/, credential/, sink/, filter/, index/uma porta cada
Composiçãoapp/, config/, cmd/*leem a config, abrem adaptadores, sobem listeners
text
AI app --MCP--> gateway (/mcp)
                  | verify token, map tools/call
                  v
                service.Call
                  | resolve exposed name -> connector + function
                  | Authorizer.Evaluate -> allow | ask_once | ask | deny
                  |-- deny  --> answers like an unknown tool
                  |-- ask   --> approval record -> pending_approval
                  '-- allow --> ConnectorRuntime.Call
                                   | credential injected
                                   v
                                ResultFilter, projection
          <---------------------- result
          outbox row, same transaction -> relay -> EventSink
  • Store: postgres (row-level security por tenant), memory e sqlite no build self-hosted.
  • ConnectorRuntime: remote (MCP), declarative (REST), grpc, skill, memory.
  • ListingSource: files, official, docker, openapi, reflection, bsr, skillcatalog.
  • SecretStore: localfile, onepassword, memory; hostkey no build self-hosted.
  • EventSink: log, webhook com assinaturas Standard Webhooks. ResultFilter: builtin. ToolIndex: lexical.
  • adapters.yaml seleciona um adaptador por porta, vários para runtimes e sources.

Ciclo de uma chamada

  1. 1AutenticarO gateway verifica o bearer token (jwks, ou o emissor local no perfil person) e mapeia tools/call para service.Call.
  2. 2Parsear os argumentos uma vezcore/args lê os argumentos antes da varredura de tokens, da checagem do schema e do hash da chamada. Recusa uma chave de objeto repetida em qualquer profundidade, um valor de nível superior que não seja objeto (null e ausente são aceitos) e dados sobrando no fim.
  3. 3AutorizarAuthorizer.Evaluate retorna allow, ask_once, ask ou deny. Deny responde exatamente como uma função desconhecida, então um agente não consegue sondar o que existe. Só uma função permitida responde invalid_argument.
  4. 4Executar ou reterAllow chega a ConnectorRuntime.Call com a credencial guardada injetada; o resultado passa por ResultFilter e pela projeção. Ask abre um registro de aprovação.
  5. 5RegistrarO evento é escrito no outbox na transação do caso de uso. relay/ o entrega ao EventSink ao menos uma vez, em ordem.

tools/list usa o mesmo caminho por Authorizer.Search, então um agente vê apenas as funções que pode chamar.

Fluxo de aprovação

?20s holdokruns once
Uma carta ask espera numa bandeja até uma pessoa carimbá-la, e então roda uma vez.
  1. 1ReterUm ask retém a chamada por approval.holdWindow (20s). Depois disso o agente recebe pending_approval com um id para consultar por approval_status ou descartar por approval_cancel.
  2. 2DecidirUma pessoa decide pela API de operador, pelo console ou por uma superfície de aprovação (desktop, Discord, Slack, Telegram, webhook).
  3. 3Rodar uma vezUma chamada aprovada roda uma vez. Uma chamada idêntica (mesma sessão, mesmo hash de chamada) se anexa ao registro aberto em vez de abrir outro.
  4. 4Nunca reenviarUma chamada encaminhada nunca é enviada de novo. Se o resultado não puder ser registrado, o agente recebe outcome_unknown, e a linha fica em started até o worker varrê-la.

Estados: pending, approved, executing, executed, failed, outcome_unknown, denied, expired, cancelled. core/approval guarda as transições; o worker roda os timers e um freio de negações.

Concessões e exposição

agent keystenantworkspaceagentuserstrictest winsallowaskdeny
Quatro camadas de concessão reduzem o chaveiro de um agente a um modo por função: allow, ask ou deny.

A avaliação percorre quatro camadas de concessão, e o modo mais estrito vence entre elas. core/evaluate guarda os passos, core/grant as regras de linha.

OrdemCamadaEfeito
1tenantopcional; restringe quando presente
2workspaceobrigatória; linha ausente nega
3agentobrigatória; linha ausente nega
4user acted foropcional; restringe quando presente
depoisteto do catálogoa visibilidade da listagem limita o modo
depoisfunções destrutivasallow vira ask_once (ou ask)
depoischecagem de exposiçãodado privado + conteúdo não confiável + caminho de saída força ask
depoisconcessão de sessãoum ask_once aprovado permite o resto da sessão

core/exposure.Check preenche as três pernas sobre as funções que seriam listadas para um agente: LegA lê dados privados, LegB devolve conteúdo de terceiros, LegC é qualquer coisa que não seja classe de leitura ou esteja marcada como open world. Uma flag não revisada conta para a sua perna, a leitura cautelosa. Exposed é true só quando as três não estão vazias.

  • Só uma linha de sessão nomeia um agente. Uma linha de tenant, workspace ou usuário com agent definido é recusada com row_refused.
  • O contador de usos de uma linha pertence ao store: só reservar um uso e restaurar um backup o alteram.
  • A migração 0003_canonical_grants reescreve stores antigos; linhas em conflito são mescladas na mais estrita e deixam uma linha de auditoria grant.merged com as originais.
  • Cada store mantém um log por tenant, monotonicamente crescente, das mudanças de configuração de acesso (permission_head, permission_changes); uma restauração só o importa para um tenant cujo log ativo esteja vazio.

Pinning

serverre-listpinnednew listhash =same: livechanged: held
Cada re-listagem é hasheada e comparada com o selo fixado; uma mudança fica retida até ser aceita.
  • Cada definição de função é hasheada como JSON canônico RFC 8785 quando capturada (core/pinning).
  • Uma função nova, ou uma descrição ou schema alterados, fica em quarentena até uma pessoa aceitar.
  • Uma concessão feita sobre um hash antigo fica obsoleta e precisa de confirmGrant.
  • Os conectores são re-listados numa agenda entre pinning.relistMin e pinning.relistMax, então um servidor que muda ferramentas após a instalação é detectado.
  • Instruções, prompts e resources do servidor são fixados do mesmo jeito quando um perfil os repassa (gateway.relayInstructions, gateway.upstreamContent).

Armazenamento e eventos

As migrações do Postgres (store/postgres/migrations) criam um schema em estilo de documentos. Todas as tabelas têm row-level security forçada, baseada na configuração cn.tenant; um role que a contorne é recusado no boot.

TabelaGuarda
recordskind, k, tenant_id, rev, doc jsonb; único por (kind, uniq); índice GIN em doc
auditlinhas de auditoria por tenant e sujeito
streams, outboxsequência por stream; linhas do outbox únicas em (stream, sequence), delivered_at nulo enquanto pendentes
inboxdeduplicação de ids consumidos por tenant
due_worktimers, indexados por due
permission_head, permission_changeso log de mudanças de configuração de acesso

A linha do outbox é escrita na mesma transação da mudança de estado. relay/ lê Outbox.Pending, entrega pelo sink com um backoff que dobra (teto de um minuto) e registra uma linha de auditoria para um evento que abandona. Os consumidores precisam deduplicar pelo id do CloudEvent.

Modelo de segurança

O motor assume que o agente e o servidor de ferramentas upstream podem ser hostis, e que o host e o seu administrador são confiáveis.

  • Segredos usam envelope encryption com uma chave por tenant; destruir a chave destrói os dados. Segredos nunca são retornados por uma API.
  • Os argumentos das chamadas são guardados como hash; o log de atividade do console oculta prováveis segredos.
  • Um guard de egress recusa endereços privados em conexões upstream, a menos que runtime.allowPrivateHosts esteja definido, e ignora HTTP_PROXY e HTTPS_PROXY porque um proxy anularia a checagem.
  • O console local escuta em 127.0.0.1 com allowlist de Host, checagens de Origin e tokens CSRF. Os apps de IA entram com OAuth 2.1 e PKCE S256.
  • A instalação sem Docker usa um diretório de dados 0700, um banco 0600 e um socket de controle que atende apenas um peer do mesmo usuário.
  • Produção recusa configurações arriscadas a menos que adapters.yaml as reconheça: local_token_issuer, long_lived_agent_tokens, trusted_proxy, manage_mcp_mutations, plaintext_root_key, private_egress.

Fora de escopo: um host ou root comprometido, acesso ao socket do Docker e leitura da memória de um processo desbloqueado.

Decisões e limites

DecisãoEscolhidoRejeitadoPor quê
Função negadaresponde como uma desconhecidaum erro forbidden explícitoum agente não consegue sondar o que existe
Definição de ferramenta alteradaquarentena até aceitar, fixada por hashconfiar na última listagemum servidor não consegue ampliar o acesso em silêncio
Entrega de eventosoutbox na mesma transação, ao menos uma vezpublicar após o commitnenhum evento se perde; duplicatas são deduplicadas por id
Chamada encaminhadanunca reenviada; outcome_unknown se o resultado se perderetryum efeito colateral aprovado roda uma vez
Código self-hostedselfhosted/ importa o núcleo, nunca o contráriouma árvore compartilhadao motor headless fica livre de código de console
Instânciasum motor por banco de dadosréplicasos caminhos multi-réplica não foram testados
  • Mais de uma réplica não é verificado: o relay pode entregar duas vezes, o worker não tem eleição de líder e as conexões OAuth pendentes vivem num mapa do processo.
  • O diretório de segredos precisa ser compartilhado e ter backup junto com o banco; linhas sem a chave raiz não podem ser abertas.
  • As portas scanner e suggester não têm adaptador embutido; os overlays vsh admin marcam as respostas de suggest como indisponíveis até um build registrar um.
  • Uma restauração de snapshot ainda não escreve suas próprias mudanças no log de permissões.
  • O repositório tem um benchmark de escritas de bindings e concessões contra muitos agentes e conectores, mas sem números publicados.

Arquivos para ler