Guide: Connectors

A connector is an MCP server muaz can launch and attach to an agent as a set of tools. The catalog on the UI Connectors page has two tiers:

• Core — the small set muaz CI-tests weekly against real servers. Verified and supported.
• Community — expected to work, but not verified by muaz (labelled as such and listed below the core group). Remote-registry entries can only present as core with a valid publisher signature; unsigned ones are shown as community.

The core connectors

Connector	Transport	Auth	What it gives an agent
GitHub	stdio (npx)	API key (PAT)	Issues, PRs, repo contents, search
Filesystem	stdio (npx)	none	Read/list/search a directory you allow-list
Fetch	stdio (uvx)	none	Fetch and read a URL as clean Markdown
Memory	stdio (npx)	none	A simple persistent key/value knowledge store
Linear	HTTP	OAuth	Issues, projects, and cycles in Linear

The stdio connectors download their runtime (Node via npx, Python via uvx) on first use — the first connect can take a moment.

When a connector actually starts — and stops

A stdio connector is a real process — Node or Python — and muaz does not start it just because a chat is open. Attaching a connector to an agent makes its tools available; the process starts the first time one of them is actually called, and is shared by every tool from that connector for the rest of the session.

muaz can do that because it remembers what each connector offers after the first successful connect, so a later session knows the tools without asking. You will see this in /mcp in the terminal: a connector reads “starts on first use” until something calls it, then turns green.

It also stops. A connector that has gone 10 minutes without a tool call is closed, and reconnects the next time one is called — so a long conversation that used a connector once at the start is not still holding a Node interpreter an hour later. The agent never notices; /mcp simply reads “starts on first use” again.

Change the window in config.yaml — 0 keeps connectors running for the whole session:

mcp_idle_timeout_secs: 1800   # 30 minutes; 0 never closes

Raise it (or set 0) for a connector holding state your session depends on — a browser automation server with a page open, say. Closing it is invisible to the agent, but whatever it was holding in memory is gone. HTTP connectors are never closed this way: there is no process to reclaim, and dropping the connection would throw away the session the server is holding for you.

Two more consequences worth knowing:

• The very first session after you add or change a connector does connect, to learn its tools. Change its command, arguments or URL and the next session re-learns them.
• Sessions never re-ask on their own, so a connector that grows a new tool stays invisible until you tell muaz to look. Reconnect on the Connectors page is that: it connects for real and refreshes what muaz remembers.

Add one (UI)

1. Open Connectors, click a core entry to prefill the form.
2. Fill any required fields — a GitHub PAT (${GITHUB_TOKEN}), the directory for Filesystem, etc. Secrets are stored in your keychain, referenced by ${VAR}.
3. Save, then Reconnect to confirm it comes up (the status chip turns green; a missing ${VAR} deep-links to the field to fix).
4. Linear uses OAuth — click Authorize to run the browser sign-in.

Attach it to an agent

Connectors are opt-in per agent. On the Agents page (or in the agent YAML), list the server under tool access and set a level per tool: off (hidden), ask (prompt each call), or auto (run freely). Keep writes at ask.

Add any other MCP server

Not in the catalog? On the Connectors page, Paste config accepts the standard shape and imports every server at once:

{
  "mcpServers": {
    "my-server": {
      "command": "npx -y @scope/my-mcp-server",
      "env": { "API_KEY": "${MY_API_KEY}" }
    }
  }
}

The command accepts an argv array or a single shell-quoted string — the same quoting rule as the UI and mcp.json. env/headers values may be literals or ${VAR} references resolved at connect time.

Put connectors to work in the Connector automation guide.