Troubleshoot your connector changedconnectors/building/troubleshooting
Nearest release: v2.1.283, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 25 Sep 2026 18:00 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 25 Sep 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+93added
Lines−86removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits3to this page, all time
# Troubleshoot your connector ## Couldn't reach the MCP server ### Hostname resolves to a private IP ### Firewall or WAF blocks traffic from Anthropic ### Your server URL redirects to a different host ### OAuth discovery fails ## Authorization with the MCP server failed ## Unexpected error while invoking tool ## Report the problem to Anthropic ## Related resources # Troubleshooting connectors ## Find your reference ID ## "Couldn't reach the MCP server" ### 1. Hostname resolves to a private IP ### 2. Firewall or WAF blocks Anthropic's traffic ### 3. Your server URL redirects to a different host ### 4. OAuth discovery fails ## "Authorization with the MCP server failed" ## "Unexpected error while invoking tool" ## Related topics
The whole hunk
from line 1, old and new numbered
/
from line 1
1# Troubleshooting connectors
1# Troubleshoot your connector
22
33> 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, 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:
5These errors appear in Claude, on claude.ai or in the desktop app, when someone uses your MCP server as a connector: either when they select **Connect** and sign in, or later when Claude calls one of your tools in a conversation. You usually meet them first yourself while [testing your server as a custom connector](/docs/connectors/building/testing#test-in-claude-as-a-custom-connector) before you submit it, and the same messages are what your users see after it's listed. Each message covers several causes on your side.
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
7This page is for the developer of the MCP server. Start with the section for the message Claude showed:
108
11## Find your reference ID
9* [Couldn't reach the MCP server](#couldn%E2%80%99t-reach-the-mcp-server): Claude can't complete the connection handshake with your server
10* [Authorization with the MCP server failed](#authorization-with-the-mcp-server-failed): the OAuth flow starts but doesn't complete, or your server URL redirects to a different host
11* [Unexpected error while invoking tool](#unexpected-error-while-invoking-tool): the connector is connected but a tool call fails
1212
13When a connection fails, the error toast and the page URL include a reference ID that starts with `ofid_`. For example:
13If none of the causes match, run the [diagnostic checklist](#diagnostic-checklist), then [report the problem to Anthropic](#report-the-problem-to-anthropic) with the reference ID from the error.
1414
15```text theme={null}
16.../customize/connectors?step=start_error&flow_id=ofid_d32594c73257a651
17```
15## Couldn't reach the MCP server
1816
19Copy that ID and include it in any GitHub issue or support request. It lets Anthropic trace the exact failure on the server side. Reference IDs are time-limited, so report them soon after the failure.
17This error appears when Claude can't complete the connection handshake. Despite the wording, it isn't always a network failure. Work through these causes in the order listed.
2018
21<Tip>
22 If you're filing on the [`anthropics/claude-ai-mcp` issue tracker](https://github.com/anthropics/claude-ai-mcp/issues), include the `ofid_` value, your server URL, and what your server-side access logs show during the Connect attempt.
23</Tip>
19### Hostname resolves to a private IP
2420
25## "Couldn't reach the MCP server"
21claude.ai connectors run on Anthropic's infrastructure and reach your server over the public internet. Before making any request, Claude resolves your server's hostname and validates the result. If any resolved address isn't globally routable, Claude rejects the connection before any HTTP request leaves Anthropic's network. Your server's access logs see nothing, and Claude reports "Couldn't reach."
2622
27This error appears when Claude can't complete the connection handshake. Despite the wording, it isn't always a network failure. Work through these causes in order.
23Claude rejects the connection when the hostname meets any of these conditions:
2824
29### 1. Hostname resolves to a private IP
25* Resolves to a private address in `10.0.0.0/8`, `172.16.0.0/12`, or `192.168.0.0/16`
26* Resolves to a carrier-grade NAT address in `100.64.0.0/10`
27* Resolves to a loopback or link-local address
28* Resolves to a mix of public and non-public addresses, because every returned address must be globally routable
29* Has no `A` record from public DNS. Connectors are IPv4-only, so a hostname that only publishes `AAAA` records can't be reached
3030
31claude.ai connectors run on Anthropic's infrastructure and reach your server over the public internet. Before making any request, Claude resolves your server's hostname and validates the result. If **any** resolved address is not globally routable, Claude rejects the connection before any HTTP request leaves Anthropic's network. Your server's access logs see nothing, and Claude reports "Couldn't reach."
31These setups commonly produce a non-routable address:
3232
33Claude rejects the connection when the hostname:
33* **Works in Claude Code or `curl` but not claude.ai**: the CLI and `curl` connect from your machine, while claude.ai connects from Anthropic's servers. If your hostname resolves differently inside and outside your network, known as split-horizon DNS, claude.ai may be getting a private IP
34* **Dynamic DNS providers**: dynamic DNS hostnames often resolve to a home network behind NAT or carrier-grade NAT
35* **Internal corporate DNS**: a hostname that resolves on your VPN won't resolve to a routable address from the public internet
3436
35* resolves to a private address (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`)
36* resolves to a carrier-grade NAT address (`100.64.0.0/10`)
37* resolves to a loopback or link-local address
38* resolves to a mix of public and non-public addresses — every returned address must be globally routable
39* has no `A` record from public DNS — connectors are IPv4-only, so a hostname that only publishes `AAAA` records can't be reached
40
41**Common gotchas:**
42
43* **Works in Claude Code or `curl` but not claude.ai.** The CLI and `curl` connect from your machine, while claude.ai connects from Anthropic's servers. If your hostname resolves differently inside and outside your network (split-horizon DNS), claude.ai may be getting a private IP.
44* **Dynamic DNS providers.** Dynamic DNS hostnames often resolve to a home network behind NAT or carrier-grade NAT.
45* **Internal corporate DNS.** A hostname that resolves on your VPN won't resolve to a routable address from the public internet.
46
4737**How to check:** Run `dig +short your-server.example.com` from a machine outside your network, or use a public DNS lookup service. Every returned address must be globally routable.
4838
49**How to fix:** Expose your server through a publicly-routable endpoint, such as a cloud host with a public IP, a public reverse proxy, or a tunnel. See [test a local server](/docs/connectors/building/testing#test-a-local-server) for the recommended tunnel setup.
39**How to fix:** Expose your server through a publicly routable endpoint, such as a cloud host with a public IP, a public reverse proxy, or a tunnel. See [test a local server](/docs/connectors/building/testing#test-a-local-server) for the recommended tunnel setup.
5040
51### 2. Firewall or WAF blocks Anthropic's traffic
41### Firewall or WAF blocks traffic from Anthropic
5242
5343If your hostname resolves correctly but a CDN, WAF, bot-management rule, or rate limiter in front of your server blocks the request, the connection fails before your application sees it.
5444
from line 46
5646
5747**How to fix:** Allowlist Anthropic's published outbound IP range in your WAF or CDN configuration, or exempt your MCP and OAuth paths from the blocking rule. The current range is on the [IP address reference](https://platform.claude.com/docs/en/api/ip-addresses) page.
5848
59### 3. Your server URL redirects to a different host
49### Your server URL redirects to a different host
6050
61If your registered MCP URL returns a `301`/`302`/`307`/`308` redirect to a different host (apex to `www.`, region routing, vanity domain to CDN), the `Authorization` header is dropped on the redirect per standard HTTP client security behavior. The redirect target receives an unauthenticated request and returns `401`, and the connection fails with "Authorization with the MCP server failed."
51If your registered MCP URL returns a `301`, `302`, `307`, or `308` redirect to a different host, such as apex to `www.`, region routing, or vanity domain to CDN, Claude drops the `Authorization` header on the redirect per standard HTTP client security behavior. The redirect target receives an unauthenticated request and returns `401`, and the connection fails with "Authorization with the MCP server failed."
6252
63This also explains the common report "works in MCP Inspector or Claude Code CLI but not claude.ai." Local clients fail fast on a redirect, so the misconfiguration is visible immediately. claude.ai follows the redirect, drops the credential, and the failure surfaces later as an authorization error.
53The dropped `Authorization` header on a redirect also explains the common report "works in MCP Inspector or Claude Code CLI but not claude.ai." Local clients fail fast on a redirect, so the misconfiguration is visible immediately. claude.ai follows the redirect, drops the credential, and the failure surfaces later as an authorization error.
6454
6555**How to check:** Run `curl -sI https://your-server.example.com/your-mcp-path` and look at the response status and `Location` header. If you see a `3xx` status pointing at a different host, that target is the URL you should register.
6656
6757**How to fix:** Register the URL your server actually listens on, not a URL that redirects to it. Common culprits are apex-to-`www.` canonicalization, geographic or region routing, and vanity-domain-to-CDN redirects.
6858
69### 4. OAuth discovery fails
59### OAuth discovery fails
7060
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:
61If 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. These are the most common causes:
7262
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.
74* **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).
75* **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.
63* **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
64* **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)
65* **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 is behind a different CDN or WAF, it must also be reachable from Anthropic's egress range. See [Serve discovery metadata](/docs/connectors/building/authentication#serve-discovery-metadata)
66* **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
7767
78**How to check:** From a public network, run:
68**How to check:** From a public network, request each discovery document:
7969
8070```bash theme={null}
8171curl -i https://your-server.example.com/.well-known/oauth-protected-resource
from line 73
8373curl -i https://your-server.example.com/.well-known/openid-configuration
8474```
8575
86If your MCP endpoint includes a path component (such as `https://your-server.example.com/mcp`), append it to the well-known path: `/.well-known/oauth-protected-resource/mcp`.
76If your MCP endpoint includes a path component, such as `https://your-server.example.com/mcp`, append it to the well-known path: `/.well-known/oauth-protected-resource/mcp`.
8777
88The protected resource metadata should return `200` with valid JSON. For authorization server metadata, your server only needs to answer **one** of the two discovery endpoints — Claude tries `/.well-known/oauth-authorization-server` ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) first, then falls back to `/.well-known/openid-configuration` ([OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)). A `404` on one is expected if the other returns `200`. Most hosted identity providers (Auth0, Okta, Microsoft Entra, Keycloak, Supabase Auth) only serve `/.well-known/openid-configuration`.
78The protected resource metadata should return `200` with valid JSON. For authorization server metadata, your server only needs to answer one of the two discovery endpoints. Claude tries `/.well-known/oauth-authorization-server` ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) first, then falls back to `/.well-known/openid-configuration` ([OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)). A `404` on one is expected if the other returns `200`. Most hosted identity providers, including Auth0, Okta, Microsoft Entra, Keycloak, and Supabase Auth, only serve `/.well-known/openid-configuration`.
8979
9080Whichever metadata document resolves should advertise a `registration_endpoint` (DCR), `"client_id_metadata_document_supported": true` (CIMD), or you should be using pre-registered credentials. In a cross-host setup, run the protected-resource curl against your MCP server and the two authorization-server curls against your authorization server's issuer host.
9181
92## "Authorization with the MCP server failed"
82## Authorization with the MCP server failed
9383
94This error usually appears after the OAuth flow has started. The most common causes:
84This error usually appears after the OAuth flow has started. These are the most common causes:
9585
96* **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.
97* **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.
98* **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.
99* **Refresh failures.** Use RFC 6749-compliant error codes when a refresh token expires. See [token refresh](/docs/connectors/building/authentication#token-refresh).
100* **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.
86* **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 but your metadata advertises a different issuer URL, validation can fail
87* **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, including any path component. The canonical form has a lowercase scheme and host, no trailing slash, no fragment, and no default port. 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
88* **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
89* **Refresh failures**: use RFC 6749-compliant error codes when a refresh token expires. See [token refresh](/docs/connectors/building/authentication#token-refresh)
90* **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)
91* **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 [Your server URL redirects to a different host](#your-server-url-redirects-to-a-different-host) for how to find and fix the redirect
10292
10393### Microsoft Entra ID rejects the resource value
10494
105If your authorization server is Microsoft Entra ID and the token request fails with `AADSTS9010010` (sometimes surfaced as `invalid_target`), Entra is rejecting the `resource` value Claude sends because it does not match any Application ID URI registered on your app. Claude sets `resource` to your MCP server URL, including the path, and Entra issues a token when that value is listed under **Expose an API** → **Application ID URI** (`identifierUris` in the manifest) on the app registration that represents your protected API. The default `api://{client-id}` URI alone is not sufficient here, because Claude sends the full MCP server URL as the resource value.
95If your authorization server is Microsoft Entra ID and the token request fails with `AADSTS9010010`, sometimes surfaced as `invalid_target`, Entra is rejecting the `resource` value Claude sends because it doesn't match any Application ID URI registered on your app. Claude sets `resource` to your MCP server URL, including the path. Entra issues a token when that value is listed under **Expose an API > Application ID URI**, which is `identifierUris` in the manifest, on the app registration that represents your protected API. The default `api://{client-id}` URI alone isn't sufficient here, because Claude sends the full MCP server URL as the resource value.
10696
107**How to fix:**
97**How to fix:** Register the MCP server URL on the API app registration:
10898
1091. In the [Microsoft Entra admin center](https://entra.microsoft.com), open the app registration that represents your protected API. If you have separate registrations for the OAuth client and the API, this is the API registration, not the client.
1102. Under **Expose an API**, add your MCP server URL as an additional [Application ID URI](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-expose-web-apis). The value must match exactly, including the path, without a trailing slash.
1113. 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.
1124. 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.
99<Steps>
100 <Step title="Open the API app registration">
101 In the [Microsoft Entra admin center](https://entra.microsoft.com), open the app registration that represents your protected API. If you have separate registrations for the OAuth client and the API, this is the API registration, not the client.
102 </Step>
113103
104 <Step title="Add the MCP server URL as an Application ID URI">
105 Under **Expose an API**, add your MCP server URL as an additional [Application ID URI](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-expose-web-apis). The value must match exactly, including the path, without a trailing slash.
106 </Step>
107
108 <Step title="Allow the API's token audiences">
109 If your server validates the token audience, such as 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.
110 </Step>
111
112 <Step title="Confirm the client's API permission">
113 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.
114 </Step>
115</Steps>
116
114117<Note>
115118 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.
116119</Note>
117120
118If 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.
121If the OAuth flow completes successfully on your server, meaning 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.
119122
120## "Unexpected error while invoking tool"
123## Unexpected error while invoking tool
121124
122125This 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.
123126
124**How to check:**
127**How to check:** Compare the failing call inside and outside Claude:
125128
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.
129<Steps>
130 <Step title="Run the call in MCP Inspector">
131 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.
132 </Step>
128133
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.
134 <Step title="Check your server's logs">
135 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.
136 </Step>
137</Steps>
130138
139If none of these is the cause, [report the problem](#report-the-problem-to-anthropic) with the tool name and the time of the failure.
140
131141## Diagnostic checklist
132142
133Run through these in order before filing an issue:
143The checklist covers every cause on this page in the order Claude encounters them during a connection. Run through it before filing an issue.
134144
135145<Steps>
136146 <Step title="Public DNS resolution">
137 From a network outside your own, confirm `dig +short your-server.example.com` returns a globally-routable address.
147 From a network outside your own, confirm `dig +short your-server.example.com` returns a globally routable address.
138148 </Step>
139149
140150 <Step title="Public reachability">
141 From a public network, confirm `curl -i https://your-server.example.com/your-mcp-path` returns a response (a `401` or `405` is fine; a timeout or connection refused is not).
151 From a public network, confirm `curl -i https://your-server.example.com/your-mcp-path` returns a response. A `401` or `405` is fine, and a timeout or connection refused is not.
142152 </Step>
143153
144154 <Step title="No redirect">
from line 160
150160 </Step>
151161
152162 <Step title="Discovery metadata">
153 Confirm `/.well-known/oauth-protected-resource` returns `200` with valid JSON, and that one of `/.well-known/oauth-authorization-server` or `/.well-known/openid-configuration` does the same — only one is needed. The authorization server metadata should include a `registration_endpoint` (DCR) or advertise `"client_id_metadata_document_supported": true` (CIMD), or you should be using pre-registered credentials, and it should advertise `"code_challenge_methods_supported": ["S256"]`.
163 Confirm `/.well-known/oauth-protected-resource` returns `200` with valid JSON, and that one of `/.well-known/oauth-authorization-server` or `/.well-known/openid-configuration` does the same. Only one is needed. The authorization server metadata should include a `registration_endpoint` (DCR) or advertise `"client_id_metadata_document_supported": true` (CIMD), or you should be using pre-registered credentials, and it should advertise `"code_challenge_methods_supported": ["S256"]`.
154164 </Step>
155165
156166 <Step title="Cross-host hint">
157 If your authorization server is on a different host than your MCP server, confirm your protected resource metadata's `authorization_servers` field points at it, and that the authorization server's host is reachable from Anthropic's egress range and answers `/.well-known/openid-configuration` (or `/.well-known/oauth-authorization-server`). See [cross-host authorization servers](/docs/connectors/building/authentication#cross-host-authorization-servers).
167 If your authorization server is on a different host than your MCP server, confirm your protected resource metadata's `authorization_servers` field points at it, and that the authorization server's host is reachable from Anthropic's egress range and answers `/.well-known/openid-configuration` or `/.well-known/oauth-authorization-server`. See [Serve discovery metadata](/docs/connectors/building/authentication#serve-discovery-metadata).
158168 </Step>
159169
160170 <Step title="Collect the reference ID">
161 Reproduce the failure and copy the `ofid_` value from the error URL. Include it, your server URL, and your server-side logs in your report.
171 Reproduce the failure and copy the `ofid_` value from the error URL, then [report the problem](#report-the-problem-to-anthropic) with it.
162172 </Step>
163173</Steps>
164174
165## Related topics
175## Report the problem to Anthropic
166176
167<Columns cols={2}>
168 <Card title="Authentication" icon="lock" href="/docs/connectors/building/authentication">
169 OAuth requirements and supported auth types.
170 </Card>
177If the checklist doesn't find the cause, report the failure on the [`anthropics/claude-ai-mcp` issue tracker](https://github.com/anthropics/claude-ai-mcp/issues). When a connection or sign-in fails on claude.ai, the error message and the page URL include a reference ID that starts with `ofid_`, for example:
171178
172 <Card title="Testing" icon="flask" href="/docs/connectors/building/testing">
173 How to test your server before publishing.
174 </Card>
179```text theme={null}
180.../customize/connectors?step=start_error&flow_id=ofid_d32594c73257a651
181```
175182
176 <Card title="Lazy authentication" icon="hourglass" href="/docs/connectors/building/lazy-authentication">
177 The 401 + WWW-Authenticate discovery handshake.
178 </Card>
183Include that ID, your server URL, and what your server-side logs show during the attempt. The ID lets Anthropic trace the exact failure on its side, and it's time-limited, so report soon after the failure. For a tool-call failure there's no reference ID; include the tool name, the time of the failure in UTC, and the connector URL instead.
179184
180 <Card title="IP address reference" icon="network-wired" href="https://platform.claude.com/docs/en/api/ip-addresses">
181 Anthropic's published IP ranges for allowlisting.
182 </Card>
183</Columns>
185## Related resources
186
187* [Authentication for connectors](/docs/connectors/building/authentication): OAuth requirements and supported auth types
188* [Lazy authentication](/docs/connectors/building/lazy-authentication): the `401` and `WWW-Authenticate` discovery handshake
189* [Test your connector](/docs/connectors/building/testing): how to test your server before publishing
190* [IP address reference](https://platform.claude.com/docs/en/api/ip-addresses): Anthropic's published IP ranges for allowlisting
184191
No line in this hunk matches that.