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.
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.
| Elemento | Valor |
|---|---|
| Consola y endpoint de agente por defecto | http://127.0.0.1:7465 y /mcp |
| Listeners del motor por defecto | server.listen :8080, server.grpcListen :9090 |
| Ventana de espera de un ask | approval.holdWindow, 20s |
| Caducidad de la aprobación | approval.timeout, 10m |
| Calendario de re-listado | pinning.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.
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 --openConecta una app y luego maneja la misma API desde la terminal con 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 approvalsEl 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.
| Archivo | Flag | Entorno |
|---|---|---|
| connector-engine.yaml | --config | CN_CONFIG |
| adapters.yaml | --adapters | CN_ADAPTERS_FILE |
| Clave | Por defecto | Significado |
|---|---|---|
| mode | production | dev relaja las comprobaciones de producción |
| server.operatorListen | "" (off) | la API de operador |
| auth.issuers | [] | emisores OIDC de confianza |
| auth.agentTokenMaxLifetime | 1h | vida máxima de un token de agente aceptado |
| permission.defaultMode | deny | una función sin permiso |
| runtime.allowPrivateHosts | false | permite que los conectores lleguen a direcciones privadas |
| gateway.skills | off | tools o tools+prompts sirve skills |
| retention.* | 0s (keep) | poda eventos, claves, auditoría y llamadas cada retention.every |
connector-engine --config connector-engine.yaml --adapters adapters.yaml adapters checkNunca 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
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/.
| Capa | Paquetes | Regla |
|---|---|---|
| Puertos | port/ | tipos neutros, interfaces, códigos de error y de motivo; sin tipos de infraestructura |
| Núcleo | core/* | funciones puras sobre tipos de port: sin I/O, sin reloj, sin globales |
| Casos de uso | service/ | una transacción del store por mutación; service/worker ejecuta timers y barridos |
| Entrada | gateway/, server/ | traducen MCP, HTTP, gRPC y MCP de gestión a casos de uso |
| Salida | store/, runtime/, source/, secrets/, auth/, credential/, sink/, filter/, index/ | un puerto cada uno |
| Composición | app/, config/, cmd/* | leen la config, abren adaptadores, arrancan 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 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
- 1AutenticarEl gateway verifica el bearer token (jwks, o el emisor local en el perfil person) y mapea tools/call a service.Call.
- 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.
- 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.
- 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.
- 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
- 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.
- 2DecidirUna persona decide mediante la API de operador, la consola o una superficie de aprobación (escritorio, Discord, Slack, Telegram, webhook).
- 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.
- 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
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.
| Orden | Capa | Efecto |
|---|---|---|
| 1 | tenant | opcional; restringe cuando está presente |
| 2 | workspace | obligatoria; una fila ausente deniega |
| 3 | agent | obligatoria; una fila ausente deniega |
| 4 | user acted for | opcional; restringe cuando está presente |
| luego | techo del catálogo | la visibilidad del listado limita el modo |
| luego | funciones destructivas | allow pasa a ask_once (o ask) |
| luego | comprobación de exposición | datos privados + contenido no confiable + vía de salida fuerza ask |
| luego | permiso de sesión | un 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
- 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.
| Tabla | Contiene |
|---|---|
| records | kind, k, tenant_id, rev, doc jsonb; único por (kind, uniq); índice GIN sobre doc |
| audit | filas de auditoría por tenant y sujeto |
| streams, outbox | secuencia por stream; filas de outbox únicas en (stream, sequence), delivered_at nulo mientras están pendientes |
| inbox | deduplicación de ids consumidos por tenant |
| due_work | timers, indexados por due |
| permission_head, permission_changes | el 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ón | Elegido | Descartado | Por qué |
|---|---|---|---|
| Función denegada | responde como una desconocida | un error forbidden explícito | un agente no puede sondear qué existe |
| Definición de herramienta cambiada | cuarentena hasta aceptarla, fijada por hash | confiar en el último listado | un servidor no puede ampliar el acceso en silencio |
| Entrega de eventos | outbox en la misma transacción, al menos una vez | publicar tras el commit | ningún evento se pierde; los duplicados se deduplican por id |
| Llamada reenviada | nunca se reenvía; outcome_unknown si se pierde el resultado | reintentar | un efecto secundario aprobado se ejecuta una vez |
| Código self-hosted | selfhosted/ importa el núcleo, nunca al revés | un árbol compartido | el motor headless queda libre de código de consola |
| Instancias | un motor por base de datos | réplicas | los 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
- ARCHITECTURE.mdcapas, camino de la llamada, permisos, aprobaciones, pinning, perfiles
- docs/reference/config.mdclaves de configuración y reconocimientos
- docs/enterprise/security-model.mdactivos, amenazas, despliegue seguro
- docs/enterprise/scaling.mdqué ejecuta una instancia y qué no está verificado
- core/exposure/exposure.gola comprobación de exposición de tres patas
- core/pinning/canonical.gohash de JSON canónico de las definiciones
- core/approval/approval.gotransiciones de estado de la aprobación
- service/gateway.gocaso de uso detrás de un tools/call
- relay/relay.goentrega del outbox al menos una vez y en orden
- store/postgres/migrations/0001_schema.sqltablas, row-level security, funciones de tenant
- gateway/call.gomanejo de llamadas MCP en el gateway
- scripts/check-layering.shhace cumplir la frontera selfhosted