Connectors

A connector is an MCP server the operator installs through the dashboard. Each connector exposes typed tools (mcp__github-app__merge_pull_request, mcp__sentry__list_issues, mcp__linear__create_issue, etc.) the agent composes to deliver an outcome. Without connectors, Zeno is a talking statue.

Connectors are the only way the agent gets external capabilities. The agent has no shell, no filesystem of its own, no general web access. If a capability is missing, the answer is to install or build a connector for it — not to script around it.

How they work

1. The operator opens /connectors in their profile dashboard. The page is read-only — every action button there opens a small modal showing the equivalent zeno connector command. Copy and run it in your terminal.
2. The CLI install flow (zeno connector install <catalog-id>) prompts for any required secrets (a PAT, an OAuth token, an API key) and POSTs the encrypted payload to the local API. Secrets are encrypted at rest with the profile's master key (AES-256-GCM).
3. The API enqueues a connector_create command. The worker picks it up, persists the row, and spawns the MCP subprocess with the right env vars on the next turn.
4. The agent's tool list now includes that connector's tools (mcp__<connector-id>__<tool-name>). The agent calls them when the operator's request matches.

Each connector ships with a list of tools it exposes; the operator can disable individual tools per connector with zeno connector tool set <slug> <tool> ask|never|always_allow to shrink the agent's surface area.

Multi-instance and the App pattern

Most connectors are plain: each install is its own row, independent. Operators with two Linear workspaces install Linear twice with --label "Acme" and --label "Personal"; the dashboard collapses them into a single connector_group card with both rows nested. Slugs are derived as linear-acme / linear-personal.

A few catalogs declare multiInstance: false. Trying to install a second one returns 409 single_instance_catalog_already_installed; the dashboard's + button is disabled with a tooltip.

github-app is the App pattern: one App entity (one PEM, one app_id) with N instances underneath (one per GitHub org/user the App is installed on). Future apps with similar shapes will follow the same pattern. The CLI exposes zeno connector app install, zeno connector app instances discover, zeno connector app instances add, and zeno connector app uninstall for this flow.

CLI reference

Every connector mutation lives in zeno connector. The dashboard's <CommandModal> always shows you the exact command for the action you clicked, including any flags or confirmation tokens needed. Common flows:

# Install a plain catalog with a label (multi-instance) or no label (single-instance)
zeno connector install linear --label "Acme workspace" --secret '__MCP_AUTHORIZATION__=lin_api_xxx'
zeno connector install sentry --secret SENTRY_ACCESS_TOKEN=sntryu_xxx

# Manage tool permissions
zeno connector tool list linear-acme
zeno connector tool set linear-acme delete_issue never
zeno connector tool bulk linear-acme --category read --permission always_allow

# Rotate or reveal a secret (rate-limited, audit-logged)
zeno connector secret rotate linear-acme
zeno connector secret reveal linear-acme __MCP_AUTHORIZATION__

# App-pattern (github-app)
zeno connector app install --catalog github-app --app-id 123456 --pem-file ~/keys/app.pem
zeno connector app instances discover
zeno connector app instances add --instance-id 125887887 --label "FNLivros"
zeno connector app uninstall --yes

# Lifecycle
zeno connector enable linear-acme
zeno connector disable linear-acme
zeno connector test linear-acme
zeno connector refresh-tools linear-acme
zeno connector uninstall linear-acme --yes

Per-tool capability gating

Every tool a connector exposes can be toggled on/off, and given a default permission of allow or ask:

• allow — the agent calls the tool without prompting.
• ask — the agent stops and asks the operator before calling.

The defaults ship with the catalogue (most read-only tools default to allow; mutating tools default to ask). The operator can override either way per profile.

Auth flow per connector

Connectors ship one of two auth shapes:

• Secret-based. The operator pastes a token into the dashboard. Examples: GitHub Personal (PAT), Linear, Klaviyo, Sentry, Swarmia.
• GitHub App. A GitHub App installation flow handles auth via short-lived installation tokens that the worker rotates on its own. One installation per connector entry, supporting multi-installation use cases (personal account + work org).

What ships today

See the connector catalogue for the full list of installable connectors with logos and descriptions. The catalogue page is generated at docs build time from agent/connectors-catalog.json, so it is always in lockstep with what the dashboard shows.

What connectors are not

• Connectors are not channels. The Slack adapter that brings messages into Zeno is a channel. A hypothetical "post to Slack" tool that the agent would call is a connector. Today, Zeno ships only the Slack channel; there is no Slack connector.
• Connectors are not skills. A skill is a markdown playbook that tells the agent how to do something. A connector is the capability that lets the agent do it at all.