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 20 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+42added
Lines−48removed
From line
96
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits4to this page, all time
The whole hunk
from line 96, old and new numbered
/
from line 96
9696
9797**How to fix:** Register the MCP server URL on the API app registration:
9898
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>
99**1. Open the API app registration**
103100
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>
101In 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.
107102
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>
103**2. Add the MCP server URL as an Application ID URI**
111104
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>
105Under **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.
116106
117<Note>
118 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.
119</Note>
107**3. Allow the API's token audiences**
120108
109If 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
111**4. Confirm the client's API permission**
112
113If 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
115> [!NOTE]
116>
117> 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.
118
121119If 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.
122120
123121## Unexpected error while invoking tool
from line 124
126124
127125**How to check:** Compare the failing call inside and outside Claude:
128126
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>
127**1. Run the call in MCP Inspector**
133128
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>
129Run 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.
138130
131**2. Check your server's logs**
132
133Check 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.
134
139135If none of these is the cause, [report the problem](#report-the-problem-to-anthropic) with the tool name and the time of the failure.
140136
141137## Diagnostic checklist
from line 138
142138
143139The checklist covers every cause on this page in the order Claude encounters them during a connection. Run through it before filing an issue.
144140
145<Steps>
146 <Step title="Public DNS resolution">
147 From a network outside your own, confirm `dig +short your-server.example.com` returns a globally routable address.
148 </Step>
141**1. Public DNS resolution**
149142
150 <Step title="Public reachability">
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.
152 </Step>
143From a network outside your own, confirm `dig +short your-server.example.com` returns a globally routable address.
153144
154 <Step title="No redirect">
155 Run `curl -sI https://your-server.example.com/your-mcp-path` and confirm the response is not a `3xx` redirect to a different host. If it is, register the redirect target instead.
156 </Step>
145**2. Public reachability**
157146
158 <Step title="No WAF block">
159 Check your edge logs for `403` or `429` responses. Allowlist Anthropic's published egress range if needed. See the [IP address reference](https://platform.claude.com/docs/en/api/ip-addresses).
160 </Step>
147From 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.
161148
162 <Step title="Discovery metadata">
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"]`.
164 </Step>
149**3. No redirect**
165150
166 <Step title="Cross-host hint">
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).
168 </Step>
151Run `curl -sI https://your-server.example.com/your-mcp-path` and confirm the response is not a `3xx` redirect to a different host. If it is, register the redirect target instead.
169152
170 <Step title="Collect the reference ID">
171 Reproduce the failure and copy the `ofid_` value from the error URL, then [report the problem](#report-the-problem-to-anthropic) with it.
172 </Step>
173</Steps>
153**4. No WAF block**
154
155Check your edge logs for `403` or `429` responses. Allowlist Anthropic's published egress range if needed. See the [IP address reference](https://platform.claude.com/docs/en/api/ip-addresses).
156
157**5. Discovery metadata**
158
159Confirm `/.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"]`.
160
161**6. Cross-host hint**
162
163If 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).
164
165**7. Collect the reference ID**
166
167Reproduce the failure and copy the `ofid_` value from the error URL, then [report the problem](#report-the-problem-to-anthropic) with it.
174168
175169## Report the problem to Anthropic
176170
No line in this hunk matches that.