Connection errors

Connector tools that fail usually fail for one of three reasons: the person has not connected their account yet, an existing connection was revoked upstream, or the upstream server itself is unreachable. The audit log tells you which.

The connection is still pending

Connectors that use per-person OAuth (Google Drive, Slack, and similar) are provisioned to the device before the person has signed in. Until they connect, every tool call for that connector returns an error that includes the authorize link.

1. Open Devices and pick the device. The provisioning preview lists "Pending connections — user must open this link in a browser to connect:" with one entry per waiting skill.
2. Select "Copy connect URL" and send the link to the person, or have them open it themselves.
3. The person signs in and approves the provider's consent screen. Harriet stores the resulting tokens; the desktop app never sees them. People can also start from My connected apps in their Harriet profile.
4. Retry the tool. No re-sync is needed for the credentials themselves; the connector works as soon as the connection exists.

The full flow, including connecting natively from Harriet Desktop, is in OAuth connections.

The upstream authorization was revoked

A connection that used to work can stop working when the authorization is revoked on the provider's side — the person removed the app from their Google or Slack account, an IT policy expired the grant, or the provider invalidated the tokens. Harriet refreshes access tokens automatically, but once the refresh token itself is dead, tool calls fail again with an error pointing at the authorize link. The fix is the same as a pending connection: reconnect through the connect URL or My connected apps.

Custom MCP servers must be public HTTPS

Harriet revalidates a custom MCP server's upstream URL before every proxied call, and only public HTTPS hosts are allowed. This is a deliberate guard: it prevents the proxy from being used as a hop into internal networks (SSRF). It also means these upstreams will never work through the proxy:

• Plain http:// URLs
• localhost or private-network addresses
• Hosts only resolvable inside your VPN or office network

Expose the server on a public HTTPS endpoint (with its own authentication), or run it as a local command on the device instead of through the proxy.

Reading the audit log

Every proxied tool call is recorded, so the audit log (Manage → Audit log) is the fastest way to see what actually failed. Each row shows the tool or MCP method, the skill, the user, and a success or error status; error rows carry an error detail that includes the upstream HTTP status code, so you can tell an upstream failure from a proxy or permission problem.

Row types to know:

• initialize — the desktop app opened the connector. Harriet answers this itself, immediately, and warms the upstream in the background. An initialize row therefore proves the device reached Harriet, not that the upstream server works.
• tools/list — only failed listings are logged; successful ones are omitted to keep the log readable. A failed tools/list row means the upstream could not be reached or refused the request.
• tools/call — the actual tool invocations, logged success or error.

By default the log hides protocol rows. Use the Show hidden toggle ("Show initialize, tools/list, and other rows omitted from the default list") when you are tracing a connection problem rather than reviewing activity.