Integrations and web search

Two Settings sections extend what agents can reach beyond your repository: Integrations ("Connect the workspaces every agent can use through provider-hosted MCP tools.") and Web search. Both apply to every product — connect once and every run that needs them can use them. See Settings for the rest of the Settings surface.

The five integrations

Motriz ships five integrations, in this order: Linear, Notion, Atlassian, AWS, and Stitch. All five are remote, provider-hosted MCP servers. Motriz runs no local server processes for them, and you never register a developer app or paste a Linear or Notion API token — four connect with OAuth in your browser. Stitch is the exception: it takes a Google Cloud API key.

Connect an integration

1. Open Settings → Integrations.

   Each integration is a card with a status badge and a setup link — for example "Linear MCP setup" or "Create a Stitch API key".

2. Choose "Connect".

   For Linear, Notion, Atlassian, and AWS, Motriz opens the provider's authorization flow in your browser and waits ("Waiting for browser…"; "Cancel" backs out). For Stitch, enter the key in the "API key" field first — the button verifies it ("Verifying key…").

3. Approve the intended workspace.

   What agents can touch is bounded by the account and workspace you authorize, not by Motriz.

4. Choose "Test connection".

   A connected card shows the workspace and account when known, "{N} tools available", and "Last checked {relative time}".

Connection states and controls

Every card carries one of five badges: not connected, connecting, connected, expired, or unavailable. The controls follow the state:

• "Test connection" verifies stored authorization on demand. Status checks are entirely local — nothing polls the providers in the background.
• "Reconnect" replaces expired OAuth authorization; for Stitch the equivalent is "Replace key". OAuth tokens also refresh themselves shortly before expiry, so routine expiry rarely needs you.
• "Try again" retries a provider that reported itself unavailable.
• "Disconnect" removes the stored authorization from this Mac.

Stored secrets are never echoed back: the Stitch key field says "The stored key is encrypted and is never shown here." If a connection stays expired or unavailable, see Troubleshooting.

Integration changes lock during runs

While any run is active, the section shows a warning — "Stop active agents before connecting, testing, reconnecting, or disconnecting integrations." — and the controls are disabled. The lock exists so an agent's tool catalog cannot change midway through its work. Stop or finish active runs, make the change, then start new work.

How agents use integration tools

Each run prepares every connected integration and exposes its tools under namespaced names of the form {integration}__{tool_name} — for example linear__create_issue. API-based providers get these tools directly in their tool loop; Claude Code receives them through a local MCP bridge that Motriz runs per run; Codex receives them as dynamic tools. You do not configure any of this — connected means available, for every agent and model. One unavailable integration never blocks the others' tools for a run.

Embedded web search

Settings → Web search configures Motriz's built-in metasearch: "Embedded metasearch every agent uses for web_search and web_fetch." The section's own summary is honest about setup — "Search runs locally against the enabled engines — no account needed. The optional Brave API key is stored encrypted in the local database."

One scoping fact worth knowing: the embedded engines serve the tool loop of API-based providers (and the deep-research sub-agent behind the deep_research tool). Claude Code and Codex agents use their own runtimes' native web tools instead, so their searches do not pass through these engines or settings.

Engines

Five engines, each with an on/off switch. All five are enabled by default.

The Brave API key field sits inline inside the Brave Search API engine row, with "Save" and "Remove" buttons. Like every stored secret, it is encrypted in the local database and never shown back to you.

A query fans out to all enabled engines concurrently, each with a five-second budget; results are deduplicated, merged, and ranked, and merged hits credit every engine that returned them. When a keyless scraper serves a captcha or anomaly page, Motriz reports it as an engine error rather than passing it off as results. Settings are re-read on every call, so an engine toggle or key change applies immediately, even to agent sessions already in flight.

Behavior

• SafeSearch — Off, Moderate, or Strict. Default: Moderate.
• Region — "Auto (engine default)" or one of eleven locales (en-US, en-GB, pt-BR, de-DE, es-ES, fr-FR, it-IT, ja-JP, nl-NL, pl-PL, zh-CN). Default: Auto.

The tools agents get

• web_search(query, count?) — searches across the enabled engines and returns ranked results as numbered title — url lines with snippets. 10 results by default, 20 at most.
• web_fetch(url) — fetches a URL and returns its readable text (HTML is reduced to headings and paragraphs; JSON and plain text pass through), with an 8-second timeout and a 2 MB body cap.
• deep_research(question, angles?) — delegates a broad question to a dedicated deep-research agent; agents are directed to lead with it for broad research and use web_search for point lookups.

Test search

Use the "Test search" box before depending on search in a long run: type into "Try a query against the enabled engines" and press "Search". Results report "{N} results from {engine labels}" with per-hit engine badges, and a failing engine shows as "{Engine}: {message}" — if one keyless scraper is temporarily blocked, the others usually still provide coverage.

What leaves your Mac

Search queries and fetched URLs go to the enabled engines and the sites you fetch. Integration tool calls go to the providers' hosted MCP services. Connection state, authorization, and keys stay on this machine, encrypted in the local database, and status checks never run in the background. The full data-boundary picture is in Privacy and safety.