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.
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.
| Item | Valor |
|---|---|
| Console e endpoint de agente padrão | http://127.0.0.1:7465 e /mcp |
| Listeners padrão do motor | server.listen :8080, server.grpcListen :9090 |
| Janela de espera de um ask | approval.holdWindow, 20s |
| Expiração da aprovação | approval.timeout, 10m |
| Agenda de re-listagem | pinning.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.
git clone https://github.com/versatile-sh/connector-engine
cd connector-engine
mise run upcurl -fsSL https://raw.githubusercontent.com/versatile-sh/connector-engine/main/scripts/install.sh | sh
vsh up --openConecte um app e depois use a mesma API pelo terminal com o vsh:
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 approvalsO 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.
| Arquivo | Flag | Ambiente |
|---|---|---|
| connector-engine.yaml | --config | CN_CONFIG |
| adapters.yaml | --adapters | CN_ADAPTERS_FILE |
| Chave | Padrão | Significado |
|---|---|---|
| mode | production | dev relaxa as verificações de produção |
| server.operatorListen | "" (off) | a API de operador |
| auth.issuers | [] | emissores OIDC confiáveis |
| auth.agentTokenMaxLifetime | 1h | maior duração de token de agente aceita |
| permission.defaultMode | deny | uma função sem concessão |
| runtime.allowPrivateHosts | false | deixa os conectores alcançarem endereços privados |
| gateway.skills | off | tools ou tools+prompts serve skills |
| retention.* | 0s (keep) | poda eventos, chaves, auditoria e chamadas a cada retention.every |
connector-engine --config connector-engine.yaml --adapters adapters.yaml adapters checkNunca 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
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/.
| Camada | Pacotes | Regra |
|---|---|---|
| Portas | port/ | tipos neutros, interfaces, códigos de erro e de motivo; sem tipos de infraestrutura |
| Núcleo | core/* | funções puras sobre tipos de port: sem I/O, sem relógio, sem globais |
| Casos de uso | service/ | uma transação do store por mutação; service/worker roda timers e varreduras |
| Entrada | gateway/, server/ | traduzem MCP, HTTP, gRPC e MCP de gerenciamento em casos de uso |
| Saída | store/, runtime/, source/, secrets/, auth/, credential/, sink/, filter/, index/ | uma porta cada |
| Composição | app/, config/, cmd/* | leem a config, abrem adaptadores, sobem listeners |
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
- 1AutenticarO gateway verifica o bearer token (jwks, ou o emissor local no perfil person) e mapeia tools/call para service.Call.
- 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.
- 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.
- 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.
- 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
- 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.
- 2DecidirUma pessoa decide pela API de operador, pelo console ou por uma superfície de aprovação (desktop, Discord, Slack, Telegram, webhook).
- 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.
- 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
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.
| Ordem | Camada | Efeito |
|---|---|---|
| 1 | tenant | opcional; restringe quando presente |
| 2 | workspace | obrigatória; linha ausente nega |
| 3 | agent | obrigatória; linha ausente nega |
| 4 | user acted for | opcional; restringe quando presente |
| depois | teto do catálogo | a visibilidade da listagem limita o modo |
| depois | funções destrutivas | allow vira ask_once (ou ask) |
| depois | checagem de exposição | dado privado + conteúdo não confiável + caminho de saída força ask |
| depois | concessão de sessão | um 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
- 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.
| Tabela | Guarda |
|---|---|
| records | kind, k, tenant_id, rev, doc jsonb; único por (kind, uniq); índice GIN em doc |
| audit | linhas de auditoria por tenant e sujeito |
| streams, outbox | sequência por stream; linhas do outbox únicas em (stream, sequence), delivered_at nulo enquanto pendentes |
| inbox | deduplicação de ids consumidos por tenant |
| due_work | timers, indexados por due |
| permission_head, permission_changes | o 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ão | Escolhido | Rejeitado | Por quê |
|---|---|---|---|
| Função negada | responde como uma desconhecida | um erro forbidden explícito | um agente não consegue sondar o que existe |
| Definição de ferramenta alterada | quarentena até aceitar, fixada por hash | confiar na última listagem | um servidor não consegue ampliar o acesso em silêncio |
| Entrega de eventos | outbox na mesma transação, ao menos uma vez | publicar após o commit | nenhum evento se perde; duplicatas são deduplicadas por id |
| Chamada encaminhada | nunca reenviada; outcome_unknown se o resultado se perde | retry | um efeito colateral aprovado roda uma vez |
| Código self-hosted | selfhosted/ importa o núcleo, nunca o contrário | uma árvore compartilhada | o motor headless fica livre de código de console |
| Instâncias | um motor por banco de dados | réplicas | os 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
- ARCHITECTURE.mdcamadas, caminho da chamada, concessões, aprovações, pinning, perfis
- docs/reference/config.mdchaves de configuração e reconhecimentos
- docs/enterprise/security-model.mdativos, ameaças, implantação segura
- docs/enterprise/scaling.mdo que uma instância roda e o que não foi verificado
- core/exposure/exposure.goa checagem de exposição de três pernas
- core/pinning/canonical.gohash de JSON canônico das definições
- core/approval/approval.gotransições de estado da aprovação
- service/gateway.gocaso de uso por trás de um tools/call
- relay/relay.goentrega do outbox ao menos uma vez e em ordem
- store/postgres/migrations/0001_schema.sqltabelas, row-level security, funções de tenant
- gateway/call.gotratamento de chamadas MCP no gateway
- scripts/check-layering.shimpõe a fronteira selfhosted