connector-engine

A gateway between AI apps and tool servers that decides, per app and per function, what runs, what waits for a person and what is refused.

Goversatile.shsource-available (GPL-3.0-or-later)Language GoLicense GPL-3.0-or-laterSurfaces MCP, HTTP, gRPCStore Postgres, SQLite, memorygithub.com/versatile-sh/connector-engine
mcprestgrpc?

Overview

connector-engine sits between your AI apps and the tool servers they call (MCP, REST, gRPC). An app talks to one endpoint, /mcp. The engine decides for each function whether it is off, on, or needs a person to approve it first.

Every function definition is pinned by an RFC 8785 hash. A tool that changes after install, or a new one, is quarantined until a person accepts it, so a server cannot widen what an agent can do without notice.

It ships in two profiles: person, a local console on 127.0.0.1 that acts as the OAuth 2.1 server for every AI app on the machine, and headless, an engine with no console that trusts your OIDC issuer and exposes an operator API and CloudEvents.

ItemValue
Default console and agent endpointhttp://127.0.0.1:7465 and /mcp
Default engine listenersserver.listen :8080, server.grpcListen :9090
Hold window for an askapproval.holdWindow, 20s
Approval expiryapproval.timeout, 10m
Re-list schedulepinning.relistMin 30s to pinning.relistMax 5m

Install and run

Prerequisites: Docker and mise for the working path today. The no-Docker installers and the release image are documented as available after v0.1.0.

ends with: 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
after v0.1.0; the installers verify the SHA-256 of every downloadsh
curl -fsSL https://raw.githubusercontent.com/versatile-sh/connector-engine/main/scripts/install.sh | sh
vsh up --open

Connect an app, then drive the same API from the terminal with 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

The engine reads two YAML files. Unknown keys are errors and a missing key keeps its default. Secrets are never written in them: a key ending in Ref takes env:NAME or file:/path.

FileFlagEnvironment
connector-engine.yaml--configCN_CONFIG
adapters.yaml--adaptersCN_ADAPTERS_FILE
KeyDefaultMeaning
modeproductiondev relaxes production checks
server.operatorListen"" (off)the operator API
auth.issuers[]trusted OIDC issuers
auth.agentTokenMaxLifetime1hlongest agent token accepted
permission.defaultModedenya function with no grant
runtime.allowPrivateHostsfalselet connectors reach private addresses
gateway.skillsofftools or tools+prompts serves skills
retention.*0s (keep)prune events, keys, audit, calls every retention.every
validates the adapter selection the way boot does; prints: adapters oksh
connector-engine --config connector-engine.yaml --adapters adapters.yaml adapters check

Never publish the console port directly. On a server use an SSH tunnel, or a TLS proxy with CONSOLE_PUBLIC_URL set. The first visitor of a new console becomes its Owner; CONSOLE_SETUP_TOKEN makes the first screen ask for a secret.

Architecture

mcpgrpcportcoreinstorerestkeys
Adapters on both sides touch the pure core only through the port ring.

Ports and adapters. Dependencies point inward: adapters import port, core imports only port, and app/ wires everything. scripts/check-layering.sh enforces that nothing in the core imports selfhosted/.

LayerPackagesRule
Portsport/neutral types, interfaces, error and reason codes; no infrastructure types
Corecore/*pure functions over port types: no I/O, no clock, no globals
Use casesservice/one store transaction per mutation; service/worker runs timers and sweeps
Inboundgateway/, server/translate MCP, HTTP, gRPC and management MCP into use cases
Outboundstore/, runtime/, source/, secrets/, auth/, credential/, sink/, filter/, index/one port each
Compositionapp/, config/, cmd/*read config, open adapters, start 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 per tenant), memory, and sqlite in the self-hosted build.
  • ConnectorRuntime: remote (MCP), declarative (REST), grpc, skill, memory.
  • ListingSource: files, official, docker, openapi, reflection, bsr, skillcatalog.
  • SecretStore: localfile, onepassword, memory; hostkey in the self-hosted build.
  • EventSink: log, webhook with Standard Webhooks signatures. ResultFilter: builtin. ToolIndex: lexical.
  • adapters.yaml selects one adapter per port, several for runtimes and sources.

Call lifecycle

  1. 1AuthenticateThe gateway verifies the bearer token (jwks, or the local issuer in the person profile) and maps tools/call to service.Call.
  2. 2Parse arguments oncecore/args reads the arguments before the token scan, schema check and call hash. It refuses a repeated object key at any depth, a non-object top-level value (null and absent are accepted) and trailing data.
  3. 3AuthorizeAuthorizer.Evaluate returns allow, ask_once, ask or deny. Deny answers exactly like an unknown function, so an agent cannot probe what exists. Only an allowed function answers invalid_argument.
  4. 4Run or holdAllow reaches ConnectorRuntime.Call with the stored credential injected; the result passes ResultFilter and projection. Ask opens an approval record.
  5. 5RecordThe event is written to the outbox in the use case's transaction. relay/ delivers it to the EventSink at least once, in order.

tools/list uses the same path through Authorizer.Search, so an agent sees only functions it may call.

Approval flow

?20s holdokruns once
An ask letter waits in a tray until a person stamps it, then runs once.
  1. 1HoldAn ask holds the call for approval.holdWindow (20s). After that the agent gets pending_approval with an id to poll through approval_status or drop through approval_cancel.
  2. 2DecideA person decides through the operator API, the console or an approval surface (desktop, Discord, Slack, Telegram, webhook).
  3. 3Run onceAn approved call runs once. An identical call (same session, same call hash) attaches to the open record instead of opening another.
  4. 4Never resendA forwarded call is never sent again. If its result cannot be recorded the agent gets outcome_unknown, and the row stays started until the worker sweeps it.

States: pending, approved, executing, executed, failed, outcome_unknown, denied, expired, cancelled. core/approval holds the transitions; the worker runs timers and a denial brake.

Grants and exposure

agent keystenantworkspaceagentuserstrictest winsallowaskdeny
Four grant layers cut an agent's key ring to one mode per function: allow, ask or deny.

Evaluation walks four grant layers, and the strictest mode wins across them. core/evaluate holds the steps, core/grant the row rules.

OrderLayerEffect
1tenantoptional; narrows when present
2workspacerequired; a missing row denies
3agentrequired; a missing row denies
4user acted foroptional; narrows when present
thencatalog ceilingthe listing's visibility caps the mode
thendestructive functionsallow becomes ask_once (or ask)
thenexposure checkprivate data + untrusted content + outbound path forces ask
thensession grantan approved ask_once allows the rest of the session

core/exposure.Check fills the three legs over the functions an agent would be listed: LegA reads private data, LegB returns third-party content, LegC is anything not a read class or marked open world. An unreviewed flag counts for its leg, the cautious reading. Exposed is true only when all three are non-empty.

  • Only a session row names an agent. A tenant, workspace or user row with agent set is refused with row_refused.
  • A row's use count belongs to the store: only reserving a use and restoring a backup change it.
  • Migration 0003_canonical_grants rewrites older stores; conflicting rows merge to the strictest and leave a grant.merged audit row holding the originals.
  • Each store keeps a per-tenant, monotonically increasing log of access-setting changes (permission_head, permission_changes); a restore imports it only for a tenant whose live log is empty.

Pinning

serverre-listpinnednew listhash =same: livechanged: held
Each re-list is hashed and compared with the pinned seal; a change is held until accepted.
  • Each function definition is hashed as RFC 8785 canonical JSON when captured (core/pinning).
  • A new function, or a changed description or schema, is quarantined until a person accepts it.
  • A grant made against an older hash goes stale and needs confirmGrant.
  • Connectors are re-listed on a schedule between pinning.relistMin and pinning.relistMax, so a server that changes tools after install is caught.
  • Server instructions, prompts and resources are pinned the same way when a profile relays them (gateway.relayInstructions, gateway.upstreamContent).

Storage and events

Postgres migrations (store/postgres/migrations) create a document-style schema. All tables have forced row-level security keyed on the cn.tenant setting; a role that bypasses it is refused at boot.

TableHolds
recordskind, k, tenant_id, rev, doc jsonb; unique per (kind, uniq); GIN index on doc
auditaudit rows per tenant and subject
streams, outboxper-stream sequence; outbox rows unique on (stream, sequence), delivered_at null while pending
inboxdedup of consumed ids per tenant
due_worktimers, indexed by due
permission_head, permission_changesthe access-setting change log

The outbox row is written in the same transaction as the state change. relay/ reads Outbox.Pending, delivers through the sink with a doubling backoff (one-minute cap), and records an audit row for an event it gives up on. Consumers must deduplicate by the CloudEvent id.

Security model

The engine assumes the agent and the upstream tool server may be hostile, and the host and its administrator are trusted.

  • Secrets use envelope encryption with a key per tenant; destroying the key shreds the data. Secrets are never returned by an API.
  • Call arguments are stored as a hash; the console activity log redacts likely secrets.
  • An egress guard refuses private addresses for upstream connections unless runtime.allowPrivateHosts is set, and ignores HTTP_PROXY and HTTPS_PROXY because a proxy would defeat the check.
  • The local console listens on 127.0.0.1 with a Host allowlist, Origin checks and CSRF tokens. AI apps sign in with OAuth 2.1 and PKCE S256.
  • The no-Docker install uses a 0700 data directory, a 0600 database and a control socket that serves only a peer of the same user.
  • Production refuses risky settings unless adapters.yaml acknowledges them: local_token_issuer, long_lived_agent_tokens, trusted_proxy, manage_mcp_mutations, plaintext_root_key, private_egress.

Out of scope: a compromised host or root, access to the Docker socket, and reading the memory of an unlocked process.

Decisions and limits

DecisionChosenRejectedWhy
Denied functionanswers like an unknown onean explicit forbidden erroran agent cannot probe what exists
Changed tool definitionquarantine until accepted, pinned by hashtrust the latest listinga server cannot widen access silently
Event deliveryoutbox in the same transaction, at least oncepublish after commitno lost events; duplicates are deduplicated by id
Forwarded callnever resent; outcome_unknown on lost resultretryan approved side effect runs once
Self-hosted codeselfhosted/ imports the core, never the reverseone shared treethe headless engine stays free of console code
Instancesone engine per databasereplicasmulti-replica paths are untested
  • More than one replica is not verified: the relay can deliver twice, the worker has no leader election, and pending OAuth connects live in a process map.
  • The secrets directory must be shared and backed up with the database; rows without the root key cannot be opened.
  • The scanner and suggester ports have no built-in adapter; vsh admin overlays suggest answers unavailable until a build registers one.
  • A snapshot restore does not yet write its own changes to the permission log.
  • The repository has a benchmark for binding and grant writes against many agents and connectors, but no published numbers.

Files to read