Connector FAQ

Quick answers to the questions that come up most when rolling out connectors: missing tools, OAuth prompts, what the audit log rows mean, and where credentials actually live.

Why isn't a tool appearing on my device?

Work down the chain. First, the tool must be Enabled on the connector's tool permissions — when a sync discovers 50 or more tools, Harriet disables new ones by default, so an admin has to opt in to each. Second, any role or group restrictions on the tool must match you. Third, a skill that attaches the connector must be assigned to you and synced to your device. If the connector uses per-user OAuth and you have not connected yet, its tools show as pending until you do — see Connecting your accounts.

Why do I keep being asked to connect my account?

A connector that requires per-user OAuth cannot run tools for you until Harriet holds tokens for your account, so every attempt fails with an authorize link until you complete the flow. Connect once through My connected apps in your account settings (or the desktop prompt) and the asking stops. If you connected before and it starts again, your grant was likely revoked or invalidated on the provider's side — reconnect the same way. Nothing needs reinstalling.

Do tool calls go directly to the vendor, or through Harriet?

Through Harriet by default. Your device talks to a per-person gateway endpoint, and Harriet forwards the call upstream with the right credentials, which is what makes tool permissions and the audit log enforceable. Admins can override transport per integration in a profile where a direct connection is preferred — see Transport.

Which tools can Harriet Desktop see for a connector?

In Harriet Desktop, open Tools, find the connector, and choose View tools from its three-dot menu. The window shows exact tool names and descriptions from the most recent supported OpenCode request for your current workspace. Search by name or description to narrow the list.

The list includes tools available through tool search, even when they have not been loaded into the model's current context. It reflects what OpenCode advertised in that request, so it may differ from the connector's administrator catalogue or from another chat or agent.

Last seen from OpenCode gives the observation time and originating chat and agent. After connector changes, sign-in changes, sync updates or a runtime restart, an older observation is marked Potentially stale. A later OpenCode request is needed to replace it. Refresh retrieves the latest saved observation; it does not start a chat, reconnect the connector or inspect a live registry.

Observations are retained for 24 hours. If none is available, check that the app and Harriet plugin are up to date and the model is routed through Harriet. A valid observation with no tools for this connector is shown separately. If connector names have overlapping prefixes, the window flags tools it cannot reliably attribute. Connectors belonging to another workspace ask you to switch there first.

Connect stays visible when sign-in is required. Sign out, Chrome settings, management and removal are in the same labelled three-dot menu.

What do the initialize rows in the audit log mean?

An initialize row is a session handshake, not a person using a tool. Harriet answers it immediately itself and uses it as a signal to warm the upstream server in the background, so it typically appears when a desktop app starts a session. Actual tool use shows up as tools/call rows.

Why don't I see tools/list rows for every session?

By design, successful tools/list calls are not logged — they happen constantly and would drown out the rows you care about. A tools/list row in the audit log therefore means the listing failed, which usually points at an upstream server problem worth investigating.

What is the usage_guide tool I see on every connector?

Harriet appends a usage_guide tool to each skill's tool list automatically. Calling it returns the skill's instructions — its SKILL.md, prompt text, or description — so the model can load how to use the tools on demand. It is expected, harmless, and not something you configure. More in Tool permissions.

Do employees ever receive our organization's API key?

No. When a connector uses a single organization secret, IT configures it once and Harriet stores it server-side; the key is used only when Harriet forwards an allowed call upstream. Employees hold nothing but a per-person, per-device gateway credential that exposes only the tools their permissions allow. If someone needs broader access, change their teams or tool permissions — never hand out the secret, and never paste it into chat or a desktop config.

Can we expose an existing REST API without building an MCP server?

Yes. If the API has an OpenAPI or Swagger document, register an OpenAPI-backed connector with the API base URL and spec URL, and Harriet generates one MCP tool per operation. Sync tools, enable only the operations people need, and attach the connector to a skill. See Custom MCP servers.

Why is a sandboxed connector slow on the first call?

Sandboxed connectors run their MCP package in Harriet's sandbox, and a cold sandbox takes time to start. Harriet returns those calls as background jobs that the desktop app polls until the result arrives, and it warms sandboxes ahead of use and caches tool lists to hide most of the delay. Subsequent calls in the same session are faster. See Hosted and sandboxed connectors.