connector-engine

Una pasarela entre apps de IA y servidores de herramientas que decide, por app y por función, qué se ejecuta, qué espera a una persona y qué se rechaza.

Goversatile.shcódigo disponible (GPL-3.0-or-later)Lenguaje GoLicencia GPL-3.0-or-laterSuperficies MCP, HTTP, gRPCAlmacenamiento Postgres, SQLite, memoriagithub.com/versatile-sh/connector-engine
mcprestgrpc?

Visión general

connector-engine se sitúa entre tus apps de IA y los servidores de herramientas que llaman (MCP, REST, gRPC). Una app habla con un único endpoint, /mcp. El motor decide para cada función si está apagada, encendida o si necesita que una persona la apruebe antes.

Cada definición de función queda fijada por un hash RFC 8785. Una herramienta que cambia tras la instalación, o una nueva, queda en cuarentena hasta que una persona la acepta, así que un servidor no puede ampliar lo que un agente puede hacer sin avisar.

Se entrega en dos perfiles: person, una consola local en 127.0.0.1 que actúa como servidor OAuth 2.1 para todas las apps de IA de la máquina, y headless, un motor sin consola que confía en tu emisor OIDC y expone una API de operador y CloudEvents.

ElementoValor
Consola y endpoint de agente por defectohttp://127.0.0.1:7465 y /mcp
Listeners del motor por defectoserver.listen :8080, server.grpcListen :9090
Ventana de espera de un askapproval.holdWindow, 20s
Caducidad de la aprobaciónapproval.timeout, 10m
Calendario de re-listadopinning.relistMin 30s a pinning.relistMax 5m

Instalar y ejecutar

Requisitos: Docker y mise para el camino que funciona hoy. Los instaladores sin Docker y la imagen de release están documentados como disponibles tras v0.1.0.

termina con: 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
tras v0.1.0; los instaladores verifican el SHA-256 de cada descargash
curl -fsSL https://raw.githubusercontent.com/versatile-sh/connector-engine/main/scripts/install.sh | sh
vsh up --open

Conecta una app y luego maneja la misma API desde la terminal con 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

El motor lee dos archivos YAML. Las claves desconocidas son errores y una clave ausente conserva su valor por defecto. Los secretos nunca se escriben en ellos: una clave que termina en Ref acepta env:NAME o file:/path.

ArchivoFlagEntorno
connector-engine.yaml--configCN_CONFIG
adapters.yaml--adaptersCN_ADAPTERS_FILE
ClavePor defectoSignificado
modeproductiondev relaja las comprobaciones de producción
server.operatorListen"" (off)la API de operador
auth.issuers[]emisores OIDC de confianza
auth.agentTokenMaxLifetime1hvida máxima de un token de agente aceptado
permission.defaultModedenyuna función sin permiso
runtime.allowPrivateHostsfalsepermite que los conectores lleguen a direcciones privadas
gateway.skillsofftools o tools+prompts sirve skills
retention.*0s (keep)poda eventos, claves, auditoría y llamadas cada retention.every
valida la selección de adaptadores como lo hace el arranque; imprime: adapters oksh
connector-engine --config connector-engine.yaml --adapters adapters.yaml adapters check

Nunca publiques el puerto de la consola directamente. En un servidor usa un túnel SSH, o un proxy TLS con CONSOLE_PUBLIC_URL definido. El primer visitante de una consola nueva se convierte en su Owner; CONSOLE_SETUP_TOKEN hace que la primera pantalla pida un secreto.

Arquitectura

mcpgrpcportcoreinstorerestkeys
Los adaptadores de ambos lados tocan el núcleo puro solo a través del anillo de puertos.

Puertos y adaptadores. Las dependencias apuntan hacia dentro: los adaptadores importan port, el núcleo importa solo port, y app/ lo conecta todo. scripts/check-layering.sh garantiza que nada del núcleo importe selfhosted/.

CapaPaquetesRegla
Puertosport/tipos neutros, interfaces, códigos de error y de motivo; sin tipos de infraestructura
Núcleocore/*funciones puras sobre tipos de port: sin I/O, sin reloj, sin globales
Casos de usoservice/una transacción del store por mutación; service/worker ejecuta timers y barridos
Entradagateway/, server/traducen MCP, HTTP, gRPC y MCP de gestión a casos de uso
Salidastore/, runtime/, source/, secrets/, auth/, credential/, sink/, filter/, index/un puerto cada uno
Composiciónapp/, config/, cmd/*leen la config, abren adaptadores, arrancan 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 y sqlite en el build self-hosted.
  • ConnectorRuntime: remote (MCP), declarative (REST), grpc, skill, memory.
  • ListingSource: files, official, docker, openapi, reflection, bsr, skillcatalog.
  • SecretStore: localfile, onepassword, memory; hostkey en el build self-hosted.
  • EventSink: log, webhook con firmas Standard Webhooks. ResultFilter: builtin. ToolIndex: lexical.
  • adapters.yaml selecciona un adaptador por puerto, varios para runtimes y sources.

Ciclo de una llamada

  1. 1AutenticarEl gateway verifica el bearer token (jwks, o el emisor local en el perfil person) y mapea tools/call a service.Call.
  2. 2Parsear los argumentos una vezcore/args lee los argumentos antes del escaneo de tokens, la validación del schema y el hash de la llamada. Rechaza una clave de objeto repetida a cualquier profundidad, un valor de nivel superior que no sea objeto (null y ausente se aceptan) y datos sobrantes al final.
  3. 3AutorizarAuthorizer.Evaluate devuelve allow, ask_once, ask o deny. Deny responde exactamente como una función desconocida, así que un agente no puede sondear qué existe. Solo una función permitida responde invalid_argument.
  4. 4Ejecutar o retenerAllow llega a ConnectorRuntime.Call con la credencial guardada inyectada; el resultado pasa por ResultFilter y la proyección. Ask abre un registro de aprobación.
  5. 5RegistrarEl evento se escribe en el outbox dentro de la transacción del caso de uso. relay/ lo entrega al EventSink al menos una vez y en orden.

tools/list usa el mismo camino a través de Authorizer.Search, así que un agente ve solo las funciones que puede llamar.

Flujo de aprobación

?20s holdokruns once
Una carta ask espera en una bandeja hasta que una persona la sella, y entonces se ejecuta una vez.
  1. 1RetenerUn ask retiene la llamada durante approval.holdWindow (20s). Después el agente recibe pending_approval con un id para consultar mediante approval_status o descartar mediante approval_cancel.
  2. 2DecidirUna persona decide mediante la API de operador, la consola o una superficie de aprobación (escritorio, Discord, Slack, Telegram, webhook).
  3. 3Ejecutar una vezUna llamada aprobada se ejecuta una vez. Una llamada idéntica (misma sesión, mismo hash de llamada) se adjunta al registro abierto en lugar de abrir otro.
  4. 4Nunca reenviarUna llamada reenviada nunca se envía de nuevo. Si no se puede registrar su resultado, el agente recibe outcome_unknown y la fila queda en started hasta que el worker la barre.

Estados: pending, approved, executing, executed, failed, outcome_unknown, denied, expired, cancelled. core/approval contiene las transiciones; el worker ejecuta los timers y un freno de denegaciones.

Permisos y exposición

agent keystenantworkspaceagentuserstrictest winsallowaskdeny
Cuatro capas de permisos reducen el llavero de un agente a un modo por función: allow, ask o deny.

La evaluación recorre cuatro capas de permisos, y gana el modo más estricto entre ellas. core/evaluate contiene los pasos, core/grant las reglas de fila.

OrdenCapaEfecto
1tenantopcional; restringe cuando está presente
2workspaceobligatoria; una fila ausente deniega
3agentobligatoria; una fila ausente deniega
4user acted foropcional; restringe cuando está presente
luegotecho del catálogola visibilidad del listado limita el modo
luegofunciones destructivasallow pasa a ask_once (o ask)
luegocomprobación de exposicióndatos privados + contenido no confiable + vía de salida fuerza ask
luegopermiso de sesiónun ask_once aprobado permite el resto de la sesión

core/exposure.Check rellena las tres patas sobre las funciones que se listarían a un agente: LegA lee datos privados, LegB devuelve contenido de terceros, LegC es cualquier cosa que no sea de clase lectura o esté marcada como open world. Una marca sin revisar cuenta para su pata, la lectura prudente. Exposed es true solo cuando las tres están no vacías.

  • Solo una fila de sesión nombra a un agente. Una fila de tenant, workspace o usuario con agent definido se rechaza con row_refused.
  • El contador de usos de una fila pertenece al store: solo reservar un uso y restaurar un backup lo cambian.
  • La migración 0003_canonical_grants reescribe los stores antiguos; las filas en conflicto se fusionan en la más estricta y dejan una fila de auditoría grant.merged con los originales.
  • Cada store mantiene un log por tenant, monótonamente creciente, de los cambios de configuración de acceso (permission_head, permission_changes); una restauración lo importa solo para un tenant cuyo log vivo esté vacío.

Pinning

serverre-listpinnednew listhash =same: livechanged: held
Cada re-listado se hashea y se compara con el sello fijado; un cambio queda retenido hasta que se acepta.
  • Cada definición de función se hashea como JSON canónico RFC 8785 al capturarse (core/pinning).
  • Una función nueva, o una descripción o schema cambiados, queda en cuarentena hasta que una persona la acepta.
  • Un permiso concedido sobre un hash anterior queda obsoleto y necesita confirmGrant.
  • Los conectores se re-listan según un calendario entre pinning.relistMin y pinning.relistMax, así se detecta un servidor que cambia herramientas tras la instalación.
  • Las instrucciones, prompts y resources del servidor se fijan igual cuando un perfil los retransmite (gateway.relayInstructions, gateway.upstreamContent).

Almacenamiento y eventos

Las migraciones de Postgres (store/postgres/migrations) crean un esquema de estilo documento. Todas las tablas tienen row-level security forzada, basada en el ajuste cn.tenant; un rol que la eluda se rechaza en el arranque.

TablaContiene
recordskind, k, tenant_id, rev, doc jsonb; único por (kind, uniq); índice GIN sobre doc
auditfilas de auditoría por tenant y sujeto
streams, outboxsecuencia por stream; filas de outbox únicas en (stream, sequence), delivered_at nulo mientras están pendientes
inboxdeduplicación de ids consumidos por tenant
due_worktimers, indexados por due
permission_head, permission_changesel log de cambios de configuración de acceso

La fila de outbox se escribe en la misma transacción que el cambio de estado. relay/ lee Outbox.Pending, entrega mediante el sink con un backoff que se duplica (tope de un minuto) y registra una fila de auditoría por un evento que abandona. Los consumidores deben deduplicar por el id del CloudEvent.

Modelo de seguridad

El motor asume que el agente y el servidor de herramientas upstream pueden ser hostiles, y que el host y su administrador son de confianza.

  • Los secretos usan cifrado de sobre con una clave por tenant; destruir la clave destruye los datos. Una API nunca devuelve los secretos.
  • Los argumentos de las llamadas se guardan como hash; el log de actividad de la consola oculta los probables secretos.
  • Un guard de egress rechaza direcciones privadas en las conexiones upstream salvo que runtime.allowPrivateHosts esté activo, e ignora HTTP_PROXY y HTTPS_PROXY porque un proxy anularía la comprobación.
  • La consola local escucha en 127.0.0.1 con una allowlist de Host, comprobaciones de Origin y tokens CSRF. Las apps de IA inician sesión con OAuth 2.1 y PKCE S256.
  • La instalación sin Docker usa un directorio de datos 0700, una base de datos 0600 y un socket de control que solo atiende a un par del mismo usuario.
  • Producción rechaza ajustes arriesgados salvo que adapters.yaml los reconozca: local_token_issuer, long_lived_agent_tokens, trusted_proxy, manage_mcp_mutations, plaintext_root_key, private_egress.

Fuera de alcance: un host o root comprometido, el acceso al socket de Docker y la lectura de la memoria de un proceso desbloqueado.

Decisiones y límites

DecisiónElegidoDescartadoPor qué
Función denegadaresponde como una desconocidaun error forbidden explícitoun agente no puede sondear qué existe
Definición de herramienta cambiadacuarentena hasta aceptarla, fijada por hashconfiar en el último listadoun servidor no puede ampliar el acceso en silencio
Entrega de eventosoutbox en la misma transacción, al menos una vezpublicar tras el commitningún evento se pierde; los duplicados se deduplican por id
Llamada reenviadanunca se reenvía; outcome_unknown si se pierde el resultadoreintentarun efecto secundario aprobado se ejecuta una vez
Código self-hostedselfhosted/ importa el núcleo, nunca al revésun árbol compartidoel motor headless queda libre de código de consola
Instanciasun motor por base de datosréplicaslos caminos multi-réplica no están probados
  • Más de una réplica no está verificado: el relay puede entregar dos veces, el worker no tiene elección de líder y las conexiones OAuth pendientes viven en un mapa del proceso.
  • El directorio de secretos debe compartirse y respaldarse junto con la base de datos; las filas sin la clave raíz no se pueden abrir.
  • Los puertos scanner y suggester no tienen adaptador integrado; los overlays vsh admin marcan las respuestas de suggest como no disponibles hasta que un build registre uno.
  • Una restauración de snapshot todavía no escribe sus propios cambios en el log de permisos.
  • El repositorio tiene un benchmark de escrituras de bindings y permisos contra muchos agentes y conectores, pero sin números publicados.

Archivos para leer