Troubleshooting

Symptom. Calls to https://ah-api.merge.dev/api/v1/... return 401 Unauthorized.

Cause. Three things to check, in order. The header format is Authorization: Bearer <KEY> - the word Bearer is required and case-sensitive. The key has been revoked or rotated; the dashboard shows the active set at Settings → API Keys. The key is from the wrong environment - test keys only work against test data, production keys only against production.

Fix. Re-copy the key from the dashboard. If you rotated recently, propagate the new value to every backend that uses it. If you’re moving from staging to production, swap to a production key and create the Registered User fresh in production.

Symptom. Link opens, the user clicks through to the third party, and on redirect back you get an error about an unauthorized origin.

Cause. The OAuth callback redirected to a domain that isn’t on your allow-list. This is a security check; Agent Handler refuses callbacks to domains it hasn’t been told to trust.

Fix. Open Settings → API Keys → Allowed callback origins and add every domain that hosts your frontend, including localhost ports for development. The match is exact, not subdomain-wildcarded - app.example.com and staging.example.com need separate entries.

Symptom. You created a Registered User in production but it shows up under test, or you can’t find a Tool Pack you’re sure you created.

Cause. Test and production environments are separate. Resources created with a test API key live only in test. The dashboard’s environment switcher (top of the registered-users page) determines which environment you’re viewing.

Fix. Check which environment you’re in, and which environment your API key belongs to. They have to match. For development, stay in test. Switch both to production when you flip on real customer onboarding.

Symptom. Calling open() on the Link component does nothing, or Link flashes briefly and closes.

Cause. Almost always one of: the link token has expired (30-minute window from creation), the link token is being reused after a successful authentication, the Registered User ID in the token doesn’t match the user you’re trying to authenticate, or the Connector slug doesn’t exist.

Fix. Generate a fresh link token on every Link session. Don’t store and reuse them. Confirm the Connector slug against the Connector catalog - slugs are lowercase with hyphens, like google-drive or microsoft-teams.

Symptom. The user completes OAuth at the third party, lands back in your app, but the Connector still shows as not authenticated.

Cause. Either the callback URL didn’t reach Agent Handler (something stripped query parameters), or the third party returned an error in the callback that Agent Handler couldn’t recover from.

Fix. Check the Tool Call Logs for an entry with the authenticate_meta tool around the time of the attempt - it’ll have the Connector’s response. If the callback URL is being rewritten by your frontend router, ensure query parameters are preserved on the redirect to Link.

Symptom. Tool call returns an error with error_type: reauth_required.

Cause. The user’s OAuth refresh token is invalid. Either it expired (rare; most providers issue long-lived refresh tokens), or it was revoked (the user disconnected the app from the provider’s settings, or the provider’s security flow invalidated it).

Fix. Generate a new link token for the same Connector and reopen Link for that user. They re-authenticate; the next tool call goes through cleanly. If this is happening frequently for one provider, check whether the OAuth scope set you’re requesting includes the offline-access scope the provider needs to issue refresh tokens.

Symptom. User connects their MCP client to https://ah-api.merge.dev/mcp, the browser opens for SSO, but they bounce back to login repeatedly.

Cause. Either the user wasn’t provisioned through SCIM (they exist in your IdP but Agent Handler hasn’t seen them yet), or the MFA setup hasn’t been completed if the org requires MFA.

Fix. From the admin dashboard, confirm the user appears in Settings → Members. If not, check your IdP’s SCIM provisioning status and trigger a manual sync. If MFA is required and the user doesn’t have it set up, an admin can reset their MFA from their member detail.

Symptom. tools/call returns an error indicating the tool doesn’t exist.

Cause. The tool name is misspelled, the tool isn’t in this Tool Pack, or the Connector isn’t enabled for this Registered User.

Fix. Confirm the tool name with tools/list first - it should be exactly <Connector>__<tool> with two underscores. Check the Tool Pack contains the Connector and the specific tool. If you recently added the tool, the pack might be cached client-side; restart your MCP client.

Symptom. Tool call returns 403 unauthorized_tool.

Cause. The tool exists in the catalog but isn’t enabled for this Tool Pack, or the Registered User has a tool-level scope restriction.

Fix. Open the Tool Pack in the dashboard and confirm the tool is checked. For the Context layer for employees setup where IdP Groups gate access, confirm the user’s Group has the Tool Pack assigned.

Symptom. A tool that should return, say, an email address has [REDACTED:EMAIL] in its place.

Cause. The Security Gateway redacted the field. This is usually intentional, but it can surprise you when you flip a rule on globally without checking which tool calls produce values that match.

Fix. Check the Alerts dashboard for the corresponding violation. If the redaction is wrong for this surface, add a per-tool-pack override to allow the entity for this pack only.

Symptom. Tool call returns error_type: rate_limit_exceeded. The error message includes the third party’s rate-limit window.

Cause. You (or your customer) hit the third party’s quota. With the default OAuth app, rate limits are scoped to Merge’s app across all customers. With your own Application Credentials, they’re scoped to your app.

Fix. Short term: back off and retry; most agents handle this gracefully if you tell them to. Long term: if you’re hitting limits often, switch the Connector to your own Application Credentials so the limits are scoped to you.

Symptom. Tool call returns billing_limit_reached.

Cause. Your account has hit its plan’s tool-call quota for the billing period.

Fix. Settings → Billing shows your current usage and lets you upgrade. Hard quotas only apply to the free and starter tiers.

Symptom. A standard entity or custom rule is matching values that shouldn’t be sensitive in your context.

Cause. Probabilistic detection has false positives. Common offenders: the URL detector firing on internal slugs that look like URLs, the location detector matching common product names, the SSN detector matching any 9-digit number.

Fix. Two options. For one Tool Pack, override the rule’s action to “allow” so it stops blocking but still logs. For all Tool Packs, raise the confidence threshold or add a custom regex with negative context keywords that suppress the false positive class.

Symptom. You can see sensitive data in the tool-call logs that should have been redacted or blocked.

Cause. Either the rule’s confidence threshold is set higher than the match’s score, or the entity type doesn’t cover the format you’re seeing.

Fix. Use the Rule Tester with a sample of the data. If the standard detector misses it, add a custom regex specifically for your format.

Symptom. You added agent-handler to claude_desktop_config.json and restarted, but no tools appear in the picker.

Cause. Either the URL or API key in the config is wrong, the mcp-remote package failed to install, or the Tool Pack has zero tools enabled.

Fix. Open Claude Desktop’s MCP logs (Settings → Developer → Open MCP Log Folder). The log shows the connection attempt and any error. The most common fix is ensuring npx and mcp-remote are reachable - Node 20+ is required.

Symptom. The server appears in the MCP picker but every tool call fails 401.

Cause. The bearer token format in the headers config is wrong. Different clients want headers in different shapes, and some won’t pass headers at all unless you use a wrapper.

Fix. Use the mcp-remote wrapper (the same one Claude Desktop uses) for clients that don’t support custom headers natively. The wrapper takes the Authorization header as a CLI flag and proxies the connection.

Symptom. Copilot Studio caps at 70 tools. Tool Packs with more than 70 tools fail to load past the limit.

Cause. A Copilot Studio constraint, not an Agent Handler one.

Fix. Split your Tool Pack into smaller packs by domain (one for CRM, one for ticketing, and so on) and connect each as a separate MCP source in Copilot Studio. See Integrating with Copilot Studio.

Symptom. merge login opens a browser but the auth never completes, or it errors with a port-bind failure.

Cause. Another process is using the localhost port the CLI tries to bind for the OAuth callback (range 9400–9410), or the browser opened in a profile that isn’t logged into Agent Handler.

Fix. Close any other Merge CLI sessions and any other processes on those ports. If your default browser is opening to a different account, log into ah.merge.dev in that browser first, then re-run merge login.