What this read moved
1–9 of 9connectors/building/troubleshooting Changed · +26 / -5 lines
## "Unexpected error while invoking tool"
from line 1
11# Troubleshooting connectors
22
3> Diagnose and resolve common connection failures for custom and directory MCP connectors
3> Diagnose and resolve common connection, authorization, and tool-call failures for custom and directory MCP connectors
44
5This page covers the most common reasons a connector fails to connect or authenticate, and how to diagnose each one. The errors Claude shows in the UI ("Couldn't reach the MCP server" and "Authorization with the MCP server failed") cover more than one root cause, so the first step is figuring out which one you're hitting.
5This page covers the most common reasons a connector fails to connect, authenticate, or run a tool, and how to diagnose each one. Each error Claude shows covers more than one root cause, so start with the section for the message you see:
66
7* "Couldn't reach the MCP server", when Claude can't complete the connection handshake
8* "Authorization with the MCP server failed", when the OAuth flow starts but doesn't complete, or when your server URL redirects to a different host
9* "Unexpected error while invoking tool", when the connector is connected but a tool call fails
10
711## Find your reference ID
812
913When a connection fails, the error toast and the page URL include a reference ID that starts with `ofid_`. For example:
from line 68
6468
6569### 4. OAuth discovery fails
6670
67If your server requires authentication, Claude performs OAuth discovery before it can connect. A discovery failure surfaces as "Couldn't reach" even though your MCP endpoint itself is reachable. The most common causes:
71If your server requires authentication, Claude performs OAuth discovery before it can connect. A discovery failure can surface as "Couldn't reach" even though your MCP endpoint itself is reachable, or as a sign-in that redirects to `/authorize` on your MCP server's host and fails there. The redirect happens when Claude can't read your [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected resource metadata and falls back to treating your MCP server's origin as the authorization server, so the browser opens a sign-in page that doesn't exist on your server. The most common causes:
6872
69* **Discovery metadata returns 404.** If your `401` response doesn't include a `WWW-Authenticate` header with a `resource_metadata` pointer, Claude looks for [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected resource metadata and authorization server metadata at the standard `/.well-known/` paths on your MCP server's origin. If those paths return `404` and you haven't pointed Claude elsewhere, Claude has no way to start the OAuth flow.
73* **Discovery metadata returns 404.** If your `401` response doesn't include a `WWW-Authenticate` header with a `resource_metadata` pointer, Claude looks for protected resource metadata and authorization server metadata at the standard `/.well-known/` paths on your MCP server's origin. If those paths return `404` and you haven't pointed Claude elsewhere, Claude can't locate your authorization server.
7074* **No way to register a client.** Claude needs one of: [RFC 7591 dynamic client registration](https://www.rfc-editor.org/rfc/rfc7591) (a `registration_endpoint` in your authorization server metadata), [Client ID Metadata Documents](/docs/connectors/building/authentication#dcr-and-cimd-details) (`"client_id_metadata_document_supported": true`), or a pre-registered client. Without any of these, Claude can't obtain a client identity. See [supported authentication types](/docs/connectors/building/authentication#supported-authentication-types).
7175* **Authorization server is on a different host than the MCP server.** Claude discovers protected resource metadata from your MCP server, then makes a *second* round of discovery requests against the authorization server host listed in `authorization_servers`. If that host lives behind a different CDN or WAF, it must also be reachable from Anthropic's egress range. See [cross-host authorization servers](/docs/connectors/building/authentication#cross-host-authorization-servers).
76* **A proxy or hosting platform alters the discovery response.** A layer in front of your server can rename or drop the `WWW-Authenticate` header, or answer `403` on the `/.well-known/` paths before the request reaches your application. Check the response at the deployed edge with `curl` from a public network, not with a tool that runs inside your platform.
7277
7378**How to check:** From a public network, run:
7479
from line 91
8691
8792## "Authorization with the MCP server failed"
8893
89This error appears after the OAuth flow has started. The most common causes:
94This error usually appears after the OAuth flow has started. The most common causes:
9095
9196* **Issuer mismatch.** The `issuer` value in your authorization server metadata must match the issuer that signs your tokens. If your tokens come from a third-party identity provider such as Supabase Auth or Auth0 but your metadata advertises a different issuer URL, validation can fail.
9297* **Audience mismatch.** The [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#token-handling) requires your server to verify each access token was issued for it. Claude sends the [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707) `resource` parameter on authorization and token requests, set to the canonical form of your MCP server URL — lowercase scheme and host, no trailing slash, no fragment, no default port — including any path component. Your authorization server should issue tokens with that audience, and your MCP server should accept the canonical value when checking `aud` rather than doing a strict byte-for-byte comparison against what the user typed. Or use whatever audience-binding mechanism your token format supports, as long as it confirms the token was minted for your server and not another service.
from line 98
9398* **PKCE not supported.** Claude includes a PKCE `code_challenge` with `code_challenge_method=S256` in every authorization request. If your authorization server doesn't implement S256 PKCE, the flow fails at the token endpoint. The [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-code-protection) also requires authorization servers to advertise `"code_challenge_methods_supported": ["S256"]` so spec-compliant clients can verify support before starting the flow.
9499* **Refresh failures.** Use RFC 6749-compliant error codes when a refresh token expires. See [token refresh](/docs/connectors/building/authentication#token-refresh).
95100* **Slow token endpoint.** Claude waits up to 10 seconds for your `/token` response; if no response bytes arrive in that window, the flow fails here even if your server eventually issues the token. Check the end-to-end latency of your token handler and any proxy or gateway in front of it. See [endpoint latency](/docs/connectors/building/authentication#endpoint-latency).
101* **Your server URL redirects to a different host.** When the URL you registered redirects to another hostname, Claude drops the `Authorization` header as it follows the redirect, the redirect target returns `401`, and the connection fails with this message. See "3. Your server URL redirects to a different host" under "Couldn't reach the MCP server" on this page for how to find and fix the redirect.
96102
97103### Microsoft Entra ID rejects the resource value
98104
from line 111
1051113. If your server validates the token audience (for example, through Azure App Service Authentication), add the API app's Application (client) ID and its `api://` URI to the allowed token audiences so your server accepts tokens issued for the API. This is the **Allowed token audiences** setting, not **Allowed client applications**, which is a different list.
1061124. If the OAuth client and the API are separate app registrations, confirm the client has an admin-consented API permission for the scope your API exposes.
107113
114<Note>
115 By default, Microsoft Entra accepts a new Application ID URI only if it contains your tenant ID, your app ID, or a domain verified in your tenant, as described in [Microsoft's identifier URI restrictions](https://learn.microsoft.com/en-us/entra/identity-platform/identifier-uri-restrictions). If your MCP server runs on a platform hostname, such as `*.azurewebsites.net`, Entra rejects that URL when you add it under **Expose an API**, so serve the server from a custom domain that your tenant has verified and register that URL instead. A tenant administrator can also exempt your app registration from this policy so that Entra accepts a noncompliant URI. Microsoft notes that an `https://` URI can require a verified domain even then, which makes the custom domain the dependable fix.
116</Note>
117
108118If the OAuth flow completes successfully on your server (you see the token issued in your logs) but the connection still fails, file a [GitHub issue](https://github.com/anthropics/claude-ai-mcp/issues) with the `ofid_` reference ID and the timestamps from your server's OAuth logs.
119
120## "Unexpected error while invoking tool"
121
122This error, followed by the name of the tool, appears when your connector shows as connected and signed in but one of its tool calls fails. Claude's tool call reached your server, and your server returned an error result for it. A failed tool call isn't a connection failure, so there is no `ofid_` reference ID for it.
123
124**How to check:**
125
1261. Run the same tool call against your server in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) and compare the result with the error Claude reports.
1272. Check your server's logs for the tool handler's error at the time of the failure, and whether the failure affects every user of your connector or one account.
128
129If you file a [GitHub issue](https://github.com/anthropics/claude-ai-mcp/issues) about a tool-call failure, include the tool name, the time of the failure in UTC, and the connector URL in place of an `ofid_` reference ID.
109130
110131## Diagnostic checklist
111132
office-agents/excel Changed · +5 / -1 lines
from line 232
232232
233233Claude for Excel does not inherit custom data retention settings your
234234organization might have set. Activity is not included in Enterprise
235audit logs or the Compliance API.
235audit logs. For Enterprise organizations with the
236[Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api)
237enabled, Claude for Excel sessions are included in the Compliance API.
238This coverage is in public beta and requires no additional setup: the
239same Compliance Access Keys apply.
236240
237241## Current limitations
238242
office-agents/outlook Changed · +7 / -3 lines
from line 438
438438or observability platform. See
439439[Configure a custom OpenTelemetry collector](/docs/office-agents/enterprise-readiness)
440440for setup. On Pro, Max, and Team plans, observability and audit
441export are not available. Claude for Outlook does not inherit custom data
442retention settings your organization may have configured and is not
443included in Enterprise audit logs or the Compliance API at this time.
441export are not available. Claude for Outlook does not inherit custom
442data retention settings your organization may have configured and is not
443included in Enterprise audit logs. For Enterprise organizations with the
444[Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api)
445enabled, Claude for Outlook sessions are included in the Compliance API.
446This coverage is in public beta and requires no additional setup: the
447same Compliance Access Keys apply.
444448
445449## Prompt injection risks
446450
office-agents/powerpoint Changed · +5 / -1 lines
from line 267
267267
268268Claude for PowerPoint does not inherit custom data retention settings
269269your organization might have set. Activity is not included in Enterprise
270audit logs or the Compliance API.
270audit logs. For Enterprise organizations with the
271[Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api)
272enabled, Claude for PowerPoint sessions are included in the Compliance
273API. This coverage is in public beta and requires no additional setup:
274the same Compliance Access Keys apply.
271275
272276## Current limitations
273277
office-agents/third-party-platforms Changed · +155 / -1 lines
## Serve add-in settings from your Claude organization ### How the sign-in works ### What served settings control ### What the add-in stores for this sign-in ### Claude account with organization-served settings
from line 71
7171| `bridge.claudeusercontent.com` | If using work across apps | WebSocket bridge for the work-across-apps feature. |
7272| `graph.microsoft.com` | If using Outlook | Microsoft Graph mailbox and calendar API. |
7373
74If your organization has
75[IP allowlisting](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)
76enabled for Claude, route `bridge.claudeusercontent.com` through the same
77proxy egress as `claude.ai` and `api.anthropic.com`, for example by
78placing it in the same Zscaler app segment or Netskope steering policy. If
79you cannot route it that way, add the egress address your proxy uses for
80that domain to your organization's Claude IP allowlist, but only when that
81address is dedicated to your organization: a shared proxy egress range also
82admits the proxy vendor's other customers.
83
84Anthropic checks connections to `bridge.claudeusercontent.com` against your
85organization's Claude IP allowlist using the address they arrive from. If
86your proxy sends traffic for that domain out through an address that is not
87on that allowlist,
88[work across apps](/docs/office-agents/work-across-apps) stops while the rest of
89the add-in keeps working.
90
7491### Third-party platforms (3P)
7592
7693Use this table if your organization signs in with Microsoft Entra ID
from line 111
94111| `<resource>.services.ai.azure.com` | If using Foundry direct | Azure AI Foundry inference endpoint; replace `<resource>` with your resource name. |
95112| `graph.microsoft.com` | If using Outlook | Microsoft Graph mailbox and calendar API. |
96113
114If Anthropic serves your add-in settings from your Claude organization,
115as described in
116[Serve add-in settings from your Claude organization](#serve-add-in-settings-from-your-claude-organization),
117also allow `claude.ai` and `api.anthropic.com`. Members sign in with
118their Claude account at `claude.ai`, and the add-in reads your
119organization's settings from `api.anthropic.com`. Inference still goes
120only to the gateway or cloud provider those settings name.
121
97122## Deploy the add-in for your organization
98123
99124Use the `claude-for-msft-365-install` plugin to configure and deploy the add-in
from line 330
305330 assignment. You can change assignment later without redeploying.
306331</Note>
307332
333## Serve add-in settings from your Claude organization
334
335Anthropic can serve the add-in's configuration to the members of a
336Claude organization directly, in place of manifest parameters, Microsoft
337Entra ID attributes, or a bootstrap endpoint. Members sign in with the
338add-in's standard "Log in" button and their Claude account. The add-in
339then reads the organization's settings from Anthropic and connects to
340the gateway or cloud provider those settings name. Prompts and responses
341still travel only to that provider, never to Anthropic.
342
343This option is in preview. It works in Anthropic's preview environments
344and is not yet enabled for production organizations. Members need the
345add-in's "Log in" button, which the Microsoft AppSource install and any
346manifest without connection parameters show.
347
348### How the sign-in works
349
350The sequence below is what a member sees. No per-member admin action is
351needed.
352
3531. The member selects "Log in" on the add-in's sign-in screen and
354 approves the sign-in in the browser with their Claude account.
3552. Anthropic's sign-in response identifies the member's organization as
356 one whose add-in settings Anthropic serves. The add-in confirms with
357 Anthropic that the account and organization on the token match that
358 response, stores the sign-in, and reloads the task pane. If the check
359 fails, the add-in discards and revokes the token and shows "Couldn't
360 verify your organization's sign-in."
3613. After the reload, the add-in reads the organization's settings from
362 `api.anthropic.com` and opens the connection screen with the served
363 values filled in, such as the gateway URL, API format, authorization
364 header, and available models. When the served settings include every
365 value the connection needs, the add-in connects without further
366 input. Otherwise the member enters the missing value, typically the
367 gateway token from your IT team, and connects.
3684. While the member stays signed in, the add-in reads the served
369 settings again at each launch and periodically while it runs, so
370 changes an admin makes apply without redeploying the manifest.
371
372### What served settings control
373
374Served settings use the same configuration keys as the manifest and a
375bootstrap endpoint, including the keys described in
376[Per-user configuration](#per-user-configuration) and
377[Admin feature controls](#admin-feature-controls). A few rules are
378specific to this path:
379
380* **Single source**: for a member signed in this way, the served
381 document is the only configuration source. The add-in does not merge
382 it with manifest parameters, Entra ID attributes, or a bootstrap
383 endpoint, and nothing from the task pane URL fills a key the served
384 document leaves out.
385* **Applied as delivered**: the add-in applies served settings the same
386 way it applies manifest configuration, with no per-setting consent
387 prompt. The Claude organization admin who edits served settings can
388 be a different person from the Microsoft 365 admin who deployed the
389 manifest.
390* **No bootstrap endpoint**: a member signed in this way uses no
391 bootstrap endpoint at all. If served settings name a `bootstrap_url`,
392 the add-in ignores it and never sends the member's token there.
393* **Last known settings at reload**: the add-in keeps the most recent
394 served document so a reloading task pane can start on it while it
395 reads the current one. The saved copy is used only for the member and
396 organization it was fetched for, and is replaced as soon as the
397 current document arrives.
398* **Settings withdrawn**: if Anthropic stops serving settings for the
399 organization, the add-in stops using any saved copy and shows "Claude
400 isn't available for your organization here" until the member signs
401 out. If the first read fails before any settings have arrived, the
402 add-in shows "Couldn't load your organization's settings" with Try
403 again and Sign out actions instead of starting on defaults.
404
405### What the add-in stores for this sign-in
406
407The sign-in is an OAuth access token and refresh token that can read
408the member's profile and the organization's add-in settings. The add-in
409also sends it with the feature-flag and telemetry requests described in
410[What Anthropic collects](#what-anthropic-collects) so those requests
411identify the signed-in member. It carries no inference access, so it
412cannot be used to send prompts to Anthropic.
413
414The add-in stores the token in localStorage within its sandboxed iframe,
415in the same place and form as a Claude account sign-in, and refreshes it
416in the background. It is not synced to Anthropic's servers. Unlike a
417Claude account sign-in, it is also not copied to the Office add-in
418storage that lets a sign-in carry across Office applications, so a
419member can be asked to log in again in another Office application or
420after Office clears the add-in's browser storage.
421
422Signing out revokes the token with Anthropic, removes it and the saved
423settings from storage, and signs the member out of any other open Claude
424task panes that share that storage.
425
426If the browser blocks the add-in's storage, for example when
427third-party site data is blocked for Office on the web, the add-in
428refuses the sign-in rather than holding it in memory only. It revokes
429the token and asks the member to allow site data for the add-in and
430select "Log in" again.
431
308432## Connection instructions for end users
309433
434### Claude account with organization-served settings
435
436Use these steps if your IT team told you to sign in with your Claude
437account and your organization's settings are served by Anthropic.
438
439<Steps>
440 <Step title="Open the add-in">
441 Open Excel, PowerPoint, Word, or Outlook and launch the Claude add-in.
442 </Step>
443
444 <Step title="Log in with your Claude account">
445 On the sign-in screen, select "Log in", then approve the sign-in in
446 the browser window that opens. The task pane reloads when the
447 sign-in is accepted.
448 </Step>
449
450 <Step title="Review the connection and connect">
451 The connection screen opens with your organization's values filled
452 in. If a field such as the gateway token is empty, enter the value
453 your IT team provided, then connect. If every value was served, the
454 add-in connects on its own.
455 </Step>
456</Steps>
457
458If another Claude task pane was already open, it shows "Reload to finish
459signing in". Select Reload in that pane.
460
310461### LLM gateway
311462
312463<Steps>
from line 947
796947and your IT team controls how that traffic is routed and logged.
797948
798949Some features that rely on a Claude account are not available through
799third-party platforms yet. Support is being added.
950third-party platforms yet. Support is being added. A member who signs in
951with a Claude account to an organization whose settings Anthropic
952serves is in the third-party platform column too, because inference
953goes to the organization's provider.
800954
801955| Feature | Claude account | Third-party platform |
802956| ------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------- |
office-agents/word Changed · +5 / -1 lines
from line 317
317317
318318Claude for Word does not inherit custom data retention settings your
319319organization might have set. Activity is not included in Enterprise
320audit logs or the Compliance API.
320audit logs. For Enterprise organizations with the
321[Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api)
322enabled, Claude for Word sessions are included in the Compliance API.
323This coverage is in public beta and requires no additional setup: the
324same Compliance Access Keys apply.
321325
322326Claude reads the content of your currently open document, including
323327text, comments, tracked changes, footnotes, tables, and bookmarks. It
office-agents/work-across-apps Changed · +7 / -3 lines
from line 124
124124
125125The Claude for M365 add-ins do not inherit custom data retention
126126settings your organization may have set, and activity is not included in
127Enterprise audit logs, the Compliance API, or data exports. Chat history
128is stored locally in your browser, not on Anthropic's servers, and can
129be cleared from Settings at any time.
127Enterprise audit logs or data exports. For Enterprise organizations with
128the [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api)
129enabled, add-in sessions are included in the Compliance API. This
130coverage is in public beta and requires no additional setup: the same
131Compliance Access Keys apply. Chat history is stored locally in your
132browser, not on Anthropic's servers, and can be cleared from Settings at
133any time.
130134
131135## Current limitations
132136
claude-tag/admins/add-connections Changed · +2 / -0 lines
from line 94
9494
9595The services with **Connect** buttons on the Credentials tab are presets, not the full set Claude can connect to. Any app with an API can be connected: click **Connect** next to **Custom tool** at the bottom of the tab. See the [Custom connection guide](/docs/claude-tag/admins/connections/custom) for the form fields, credential types, and how to add a custom MCP server.
9696
97You can also add connections from a channel's [Configure page](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel). The option to add one appears there only for people who can manage Claude's setup for that channel or for the whole organization. [Channel managers](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) can manage setup for their assigned channels. Other channel members see the channel's connections on the Configure page but can't add one.
98
9799## Allow a host without a credential
98100
99101Claude does channel work in an isolated [sandbox](/docs/claude-tag/concepts/agent-identity#channel-sessions). A network request is traffic that sandbox sends to a host, such as an API call, a `curl` fetch, or a package install. Before Claude can make one from a channel, the destination host has to be allowed by one of three settings, the allow layers:
connectors/building/authentication Changed · +1 / -1 lines
from line 74
7474* Your authorization server must serve its own discovery metadata — [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) authorization server metadata or [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) — at its `/.well-known/` paths, and that host must also be reachable from Anthropic's [published egress range](https://platform.claude.com/docs/en/api/ip-addresses). Discovery requests to the authorization server come from the same IP range as requests to your MCP server, so a WAF in front of your identity provider can break the flow even when your MCP server is reachable.
7575
7676<Note>
77 If your authorization server is Microsoft Entra ID, you must also register the MCP server URL as an Application ID URI on your Entra app registration, or the token request fails with `AADSTS9010010`. See [the troubleshooting entry](/docs/connectors/building/troubleshooting#microsoft-entra-id-rejects-the-resource-value) for the fix.
77 If your authorization server is Microsoft Entra ID, you must also register the MCP server URL as an Application ID URI on your Entra app registration, or the token request fails with `AADSTS9010010`. By default, Entra accepts that URL as an Application ID URI only when it's on a domain your tenant has verified (see [Microsoft's identifier URI restrictions](https://learn.microsoft.com/en-us/entra/identity-platform/identifier-uri-restrictions)), so an MCP server on a platform hostname such as `*.azurewebsites.net` needs a custom domain first. See [the troubleshooting entry](/docs/connectors/building/troubleshooting#microsoft-entra-id-rejects-the-resource-value) for the fix.
7878</Note>
7979
8080If you control both hosts, an alternative is to serve the MCP endpoint and the authorization server behind a single custom domain that can route both `/.well-known/*` and your MCP path.