Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
1,632 changes: 808 additions & 824 deletions content/.metadata.json

Large diffs are not rendered by default.

1 change: 0 additions & 1 deletion content/claude-code-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,6 @@
"_nodeVersion": "24.20.0",
"dependencies": {},
"_hasShrinkwrap": false,
"readmeFilename": "README.md",
"optionalDependencies": {
"@anthropic-ai/claude-code-linux-x64": "2.1.268",
"@anthropic-ai/claude-code-win32-x64": "2.1.268",
Expand Down
2 changes: 2 additions & 0 deletions content/claude/claude-tag/admins/add-connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,8 @@ For a shared or external channel, put the narrowed connection in its own bundle

The 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.

You 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.

## Allow a host without a credential

Claude 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:
Expand Down
2 changes: 1 addition & 1 deletion content/claude/connectors/building/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ Whichever way Claude finds the document:
* 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.

<Note>
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.
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.
</Note>

If 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.
Expand Down
31 changes: 26 additions & 5 deletions content/claude/connectors/building/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,13 @@

# Troubleshooting connectors

> Diagnose and resolve common connection failures for custom and directory MCP connectors
> Diagnose and resolve common connection, authorization, and tool-call failures for custom and directory MCP connectors

This 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.
This 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:

* "Couldn't reach the MCP server", when Claude can't complete the connection handshake
* "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
* "Unexpected error while invoking tool", when the connector is connected but a tool call fails

## Find your reference ID

Expand Down Expand Up @@ -68,11 +72,12 @@ This also explains the common report "works in MCP Inspector or Claude Code CLI

### 4. OAuth discovery fails

If 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:
If 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:

* **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.
* **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.
* **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).
* **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).
* **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.

**How to check:** From a public network, run:

Expand All @@ -90,13 +95,14 @@ Whichever metadata document resolves should advertise a `registration_endpoint`

## "Authorization with the MCP server failed"

This error appears after the OAuth flow has started. The most common causes:
This error usually appears after the OAuth flow has started. The most common causes:

* **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.
* **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.
* **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.
* **Refresh failures.** Use RFC 6749-compliant error codes when a refresh token expires. See [token refresh](/docs/connectors/building/authentication#token-refresh).
* **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).
* **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.

### Microsoft Entra ID rejects the resource value

Expand All @@ -109,8 +115,23 @@ If your authorization server is Microsoft Entra ID and the token request fails w
3. 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.
4. 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.

<Note>
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.
</Note>

If 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.

## "Unexpected error while invoking tool"

This 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.

**How to check:**

1. 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.
2. 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.

If 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.

## Diagnostic checklist

Run through these in order before filing an issue:
Expand Down
6 changes: 5 additions & 1 deletion content/claude/office-agents/excel.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,11 @@ for where it sits on disk and how long it is kept.

Claude for Excel does not inherit custom data retention settings your
organization might have set. Activity is not included in Enterprise
audit logs or the Compliance API.
audit logs. For Enterprise organizations with the
[Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api)
enabled, Claude for Excel sessions are included in the Compliance API.
This coverage is in public beta and requires no additional setup: the
same Compliance Access Keys apply.

## Current limitations

Expand Down
10 changes: 7 additions & 3 deletions content/claude/office-agents/outlook.md
Original file line number Diff line number Diff line change
Expand Up @@ -442,9 +442,13 @@ Outlook to their own OpenTelemetry collector for integration with a SIEM
or observability platform. See
[Configure a custom OpenTelemetry collector](/docs/office-agents/enterprise-readiness)
for setup. On Pro, Max, and Team plans, observability and audit
export are not available. Claude for Outlook does not inherit custom data
retention settings your organization may have configured and is not
included in Enterprise audit logs or the Compliance API at this time.
export are not available. Claude for Outlook does not inherit custom
data retention settings your organization may have configured and is not
included in Enterprise audit logs. For Enterprise organizations with the
[Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api)
enabled, Claude for Outlook sessions are included in the Compliance API.
This coverage is in public beta and requires no additional setup: the
same Compliance Access Keys apply.

## Prompt injection risks

Expand Down
6 changes: 5 additions & 1 deletion content/claude/office-agents/powerpoint.md
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,11 @@ for where it sits on disk and how long it is kept.

Claude for PowerPoint does not inherit custom data retention settings
your organization might have set. Activity is not included in Enterprise
audit logs or the Compliance API.
audit logs. For Enterprise organizations with the
[Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api)
enabled, Claude for PowerPoint sessions are included in the Compliance
API. This coverage is in public beta and requires no additional setup:
the same Compliance Access Keys apply.

## Current limitations

Expand Down
Loading
Loading