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.

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.