Hosted and sandboxed connectors

Every catalog template carries one of three install modes: Hosted remote MCP, Harriet sandboxed, or Guided external setup. The mode tells you where the MCP server actually runs and what to expect at runtime.

Hosted remote MCP

The vendor operates the MCP server, and Harriet's gateway forwards tool calls to its public HTTPS endpoint. Slack, Atlassian, and Asana in the catalog work this way, pointing at the vendors' official remote servers.

This is the lowest-maintenance mode: no package to run, and the vendor keeps the tools current. These templates typically use per-user OAuth, so each call runs with the permissions of the person who made it.

Harriet sandboxed

Harriet runs the MCP server itself, inside an isolated sandbox. The connector specifies a package command (npx or uvx plus arguments), and Harriet executes it in that environment — the catalog's Google Drive and Google Docs templates run community MCP packages this way.

Sandboxes are started on demand, and a cold start can take longer than a normal web request. Rather than time out, Harriet answers some sandboxed calls with a background job that the desktop app polls until the result is ready. In practice this means an async job may return its result a little later than a hosted call would; the bridge on the device handles the waiting transparently, so people just see the tool take a moment longer.

Harriet softens this in two ways: it warms sandboxes in the background when a session starts, and it caches each server's tool list so the tools appear immediately while the live server spins up.

Set up per-user OAuth for a sandboxed connector

A sandboxed connector can run with each person's own sign-in to the service it calls. Ask the agent to set it up (in Harriet Desktop or with Bot Configurator), or fill in the same settings yourself on the connector's Options and Sandbox tabs.

1. Register an OAuth app with the provider. Add the redirect URI shown on the connector's Options tab. The agent can read it out to you.
2. Enter the app's details. The client ID, authorization URL, token URL and scopes go on the Options tab. A sandboxed connector can't look these up for itself, so copy them from the provider's documentation.
3. Enter the client secret. In Harriet Desktop the agent opens a private form, so the secret never goes into the chat. Otherwise type it into OAuth client secret. It is stored encrypted and never shown again.
4. Choose how the sign-in reaches the connector on the Sandbox tab. Per-user OAuth delivery is how the connector receives it, and Per-user OAuth env var name is the variable it reads. Leave Per-user OAuth credential policy on Access only: Harriet refreshes the sign-in itself and the connector never receives a refresh token. A connector set to Access only receives nothing through the default token file, so pick Access token value if its package reads a token from an environment variable.
5. Connect your account. In Harriet Desktop the agent shows a Connect button in the chat. Otherwise connect from Connected apps. Then run Sync tools.

Some provider-specific settings, such as turning PKCE off or leaving the trailing slash off the redirect URI, have no field in the form. The agent can set them, and the Options tab lists them under Advanced sign-in settings, read-only. Ask the agent to change them. The Refresh capable policy is an exception that only an admin can choose in the form.

Guided external setup

Some apps need work outside Harriet before a connector can function, typically registering an app in the vendor's own admin console and granting it permissions there. Guided templates, like Microsoft 365 in the catalog, walk an admin through that setup and collect the resulting details. After the guided steps, the connector behaves like a hosted remote MCP.

Choosing between them

Whatever the mode, calls flow through Harriet's gateway with the same tool permissions and the same audit log. Only public HTTPS hosts are allowed upstream, and hosted server URLs are revalidated before each call.