Table of contents
- Quick summary
- Why a strict client refuses the document
- The lab: seven documents, one SDK
- Fix each cause
- 1. You proxy your identity provider's metadata
- 2. Your issuer has a path, the file is at the root
- 3. A trailing slash on one side
- 4. The resource file names another issuer
- Check it: the scan, then the three strings
- What not to do
- Related guides
- Your next step
An MCP client that says "issuer mismatch" has fetched your OAuth authorization server metadata and found an issuer value that is not, character for character, the string it used to build that URL. RFC 8414 §3.3 tells it to throw the document away, so sign-in stops before the login page ever opens. It is almost always one of four mistakes, each fixed by changing one string, and you can confirm the fix in under a minute with the 30-line checker below.
Quick summary
| What you see | Cause | Fix |
|---|---|---|
issuer mismatch: https://idp.example.com/... != https://your-site | Metadata proxied verbatim from your identity provider | Point authorization_servers at the IdP's issuer instead of proxying its file |
| No metadata found, then a fallback or a failure | Path issuer, file only at the root | Serve the file at /.well-known/oauth-authorization-server/<path> |
.../auth/ != .../auth | Trailing slash on one side only | Make issuer and authorization_servers the same string |
https://your-site != https://your-site/oauth | The protected-resource file names a different issuer | Copy the issuer value into authorization_servers exactly |
All four were reproduced on 15 Nov 2026 against the MCP Python SDK 2.3.0; the raw output is further down.
Why a strict client refuses the document
Discovery is a chain of three strings. The client reads your protected-resource file (RFC 9728) and takes the first entry in authorization_servers. That entry is an issuer identifier. The client inserts /.well-known/oauth-authorization-server between its host and its path, fetches the result, and reads the issuer field inside.
| String | Where it lives | Example |
|---|---|---|
| 1. Issuer the client trusts | authorization_servers[0] in /.well-known/oauth-protected-resource | https://example.com/oauth |
| 2. URL the client builds | well-known suffix inserted before the path | https://example.com/.well-known/oauth-authorization-server/oauth |
| 3. Issuer the server claims | issuer inside the file at string 2 | must be https://example.com/oauth |
RFC 8414 §3.3 is short and absolute. In its own words, the returned issuer "MUST be identical to the authorization server's issuer identifier value into which the well-known URI string was inserted", and if they differ "the data contained in the response MUST NOT be used." According to Section 4 of the same RFC, the comparison is code point by code point, with no normalisation. So https://a.example/auth and https://a.example/auth/ are two different issuers, even though §3.1 strips the trailing slash when it builds the URL and both fetch the same file.
The rule exists to stop a malicious server from handing out metadata that claims to be someone else. A mismatch looks exactly like that attack to the client, so a well-built client does not offer a workaround.
According to the MCP authorization spec (2025-11-25), one more detail trips path issuers. For an issuer with a path such as https://auth.example.com/tenant1, clients must try the path-inserted OAuth URL, then two OpenID Connect variants. The root file is not on that list.
The lab: seven documents, one SDK
We served seven pairs of metadata files from Python's http.server on localhost and ran the discovery steps of the MCP Python SDK against each: the SDK's own URL builders (build_protected_resource_metadata_discovery_urls, build_oauth_authorization_server_metadata_discovery_urls) and its own check, validate_metadata_issuer, from mcp.client.auth.utils. Raw output, verified on 15 Nov 2026:
case 1 | origin issuer, file at root | OK (.well-known/oauth-authorization-server)
case 2 | path issuer, file only at root | no AS metadata at any URL the SDK tries
case 3 | path issuer, file at path-inserted URL | OK (.well-known/oauth-authorization-server/auth)
case 4 | trailing slash on a path issuer | RAISE OAuthFlowError: Authorization server metadata issuer mismatch: http://localhost:8704/auth/ != http://localhost:8704/auth
case 5 | IdP metadata proxied verbatim | RAISE OAuthFlowError: Authorization server metadata issuer mismatch: https://idp.example.com/realms/acme != http://localhost:8705
case 6 | PRM names a different issuer | RAISE OAuthFlowError: Authorization server metadata issuer mismatch: http://localhost:8706 != http://localhost:8706/oauth
case 7 | trailing slash on a root issuer | RAISE OAuthFlowError: Authorization server metadata issuer mismatch: http://localhost:8707/ != http://localhost:8707
Two results surprised us. Case 2 never reaches the issuer check at all: with a path issuer the SDK does not look at the root file, so the error is "not found" rather than "mismatch", and it is the same misconfiguration. Case 7 fails even at the root. According to the SDK's source (oauth2.py, 2.3.0), it forgives a root trailing slash only on the legacy path for servers with no protected-resource file; once your protected-resource file names the issuer, the comparison is exact.
| Case | Error a client shows | Who usually causes it |
|---|---|---|
| 2 | metadata not found | a framework that mounts the auth routes under a prefix |
| 4, 7 | issuer mismatch, differing by / | a config value typed by hand in two places |
| 5 | issuer mismatch, foreign host | a reverse proxy in front of a hosted identity provider |
| 6 | issuer mismatch, path differs | moving the auth server without updating the resource file |
Fix each cause
1. You proxy your identity provider's metadata
If your server fetches the IdP's document and re-serves it from your own domain, the issuer inside still names the IdP. Do not rewrite the issuer to your domain: the IdP signs tokens with its own iss, and a client that validates tokens will then fail one step later.
- Stop serving
/.well-known/oauth-authorization-serverfrom your MCP host. - In
/.well-known/oauth-protected-resource, set"authorization_servers": ["<the IdP's issuer, copied from its own metadata>"]. - Clients now fetch the IdP's metadata from the IdP's host, where the strings match.
This is how aiscan.site does it: its protected-resource file names a hosted Supabase Auth issuer with a path (https://<project>.supabase.co/auth/v1), and the client fetches the metadata from Supabase directly.
2. Your issuer has a path, the file is at the root
Serve the same JSON at the path-inserted URL. For issuer https://example.com/oauth that is https://example.com/.well-known/oauth-authorization-server/oauth. Keep the root copy only if a client built to the 2025-03-26 revision of MCP still needs it; xspeedcache.com serves its /oauth issuer at the path-inserted URL and passes.
3. A trailing slash on one side
Pick one form and paste it in both places. The simplest rule is no trailing slash anywhere, because §3.1 strips it when building the URL anyway.
4. The resource file names another issuer
Open both files side by side. The string in authorization_servers[0] must be the string in issuer. If you moved the auth server, update the resource file in the same deploy.
Check it: the scan, then the three strings
Run the scan first: npx aiscan-cli yoursite.com, or paste the URL at aiscan.site. Check P4 tells you whether both well-known files answer. It does not compare the issuer strings, so a P4 pass can still fail sign-in; the capabilities checks page lists exactly what P4 reads.
To compare the strings by hand, save this as issuer_check.py (Python 3, standard library only) and give it your MCP server URL:
#!/usr/bin/env python3
"""issuer_check.py <mcp-server-url>: compare the three issuer strings (RFC 9728 + RFC 8414 §3.3)."""
import json, sys, urllib.request, urllib.error
from urllib.parse import urlsplit
def get(url):
try:
with urllib.request.urlopen(urllib.request.Request(url, headers={"Accept": "application/json"}), timeout=15) as r:
return json.load(r)
except (urllib.error.URLError, ValueError):
return None
server = sys.argv[1]
u = urlsplit(server); origin = f"{u.scheme}://{u.netloc}"; path = u.path.rstrip("/")
prm_urls = ([f"{origin}/.well-known/oauth-protected-resource{path}"] if path else []) + [f"{origin}/.well-known/oauth-protected-resource"]
prm = prm_url = None
for x in prm_urls:
prm = get(x)
if prm: prm_url = x; break
if not prm:
sys.exit("no protected-resource metadata: a client falls back to the origin " + origin)
issuer = prm["authorization_servers"][0]
i = urlsplit(issuer); ipath = i.path.rstrip("/")
as_url = f"{i.scheme}://{i.netloc}/.well-known/oauth-authorization-server{ipath}"
asm = get(as_url)
print("PRM ", prm_url)
print("issuer want", repr(issuer))
print("AS file ", as_url, "->", "200" if asm else "not found")
print("issuer got ", repr(asm.get("issuer")) if asm else "-")
print("RESULT ", "MATCH" if asm and asm.get("issuer") == issuer else "MISMATCH")
Output on our own two MCP servers, fetched from the live sites on 15 Nov 2026:
$ python3 issuer_check.py https://xspeedcache.com/mcp
PRM https://xspeedcache.com/.well-known/oauth-protected-resource/mcp
issuer want 'https://xspeedcache.com/oauth'
AS file https://xspeedcache.com/.well-known/oauth-authorization-server/oauth -> 200
issuer got 'https://xspeedcache.com/oauth'
RESULT MATCH
$ python3 issuer_check.py https://aiscan.site/mcp
PRM https://aiscan.site/.well-known/oauth-protected-resource
issuer want 'https://<project>.supabase.co/auth/v1'
AS file https://<project>.supabase.co/.well-known/oauth-authorization-server/auth/v1 -> 200
issuer got 'https://<project>.supabase.co/auth/v1'
RESULT MATCH
MATCH with a 200 is the pass. MISMATCH prints both strings in quotes so a stray slash is visible. The same test with curl and jq:
curl -s https://example.com/.well-known/oauth-protected-resource | jq -r '.authorization_servers[0]'
curl -s https://example.com/.well-known/oauth-authorization-server/oauth | jq -r '.issuer'
The two lines must print the same string.
What not to do
- Do not ask users to switch clients. The Python SDK enforces §3.3 as shown above, and any client written to the RFC must do the same, because the RFC says MUST.
- Do not rewrite a proxied
issuerto your own domain. You trade a discovery error for a token validation error. - Do not add a trailing slash "to be safe". It is the cause in two of the seven lab cases.
Who can skip this: if your MCP server needs no sign-in, you publish neither file and none of this applies.
Related guides
The full discovery chain is in OAuth discovery for agents. If the protected-resource file itself is at the wrong path, read the protected-resource path fix. How many sites publish these files, and how our own WordPress sites fared against the same SDK, is in the OAuth discovery corpus.
Your next step
Scan your site at aiscan.site, confirm P4 passes, then run issuer_check.py against your MCP URL until it prints MATCH. Fix guides for every other check are at /guides.
Frequently asked questions
My MCP client says "Authorization server metadata issuer mismatch". What does that mean?
The issuer inside your /.well-known/oauth-authorization-server file is not the exact string the client used to build that URL. RFC 8414 §3.3 tells the client to discard the document, so sign-in stops. Compare authorization_servers[0] in your protected-resource file with the issuer value; they must be identical.
The error shows two URLs that differ only by a trailing slash. Is that really a failure?
Yes. RFC 8414 compares issuers code point by code point with no normalisation, so https://example.com/auth/ and https://example.com/auth are different issuers. In our 15 Nov 2026 lab the MCP Python SDK 2.3.0 raised on both a path issuer and a root issuer with a stray slash. Remove the slash from one side.
My client reports no authorization server metadata found, but the file exists at the root. Why?
Your issuer has a path. For an issuer like https://example.com/oauth, the MCP spec and RFC 8414 §3.1 send the client to /.well-known/oauth-authorization-server/oauth, not to the root file. Serve the same JSON at the path-inserted URL.
I proxy Keycloak's metadata through my own domain and get an issuer mismatch. Should I rewrite the issuer?
No. Tokens are still signed with the identity provider's own iss, so rewriting moves the failure to token validation. Name the provider's issuer in authorization_servers and let the client fetch its metadata from the provider's host.
Does AIScan's P4 check catch an issuer mismatch?
No. P4 checks that the OAuth discovery files answer at their well-known paths. It does not compare issuer strings, so a site can pass P4 and still fail sign-in. Run the checker in this guide after the scan.
Which string is the source of truth: the issuer or the protected-resource entry?
The authorization server's issuer is its identity and is what appears in tokens, so treat it as fixed and copy it into authorization_servers in your protected-resource file.
Can I serve the metadata at both the root and the path-inserted URL?
Yes, as long as both copies carry the same issuer. Older clients built to the 2025-03-26 MCP revision fetch the root file and expect the origin as issuer, so a path issuer at the root can still trip them; the path-inserted copy is the one current clients read.
How do I test the fix without an MCP client?
Run the 30-line issuer_check.py from this guide against your MCP server URL, or compare jq -r '.authorization_servers[0]' on the protected-resource file with jq -r '.issuer' on the authorization server file. Both should print the same string.

About the author
M Asif Rahman
Entrepreneur, curious about AI
I have been building companies for a long time, and lately most of my curiosity goes to AI. AIScan is a small personal project I built on a flight from Dubai to Narita. I use it to understand how ready the web is for AI agents, and I share what the scans teach me.
Related guides
OAuth Discovery Metadata on 806 Sites: 133 Pass, and 47 of 50 Soft 200s Fail E1
Of 806 hosts in our scan corpus, 133 pass check P4, the OAuth discovery check. That is 16.5%. The more useful number is 50. fifty hosts answered HTTP 200 at an OAuth metadata path and still did not…
CORS on Agent Discovery Files: Why Browser Agents Can't Read Your /.well-known/, llms.txt and OpenAPI
If an agent in a browser tab cannot read your /.wellknown/ files, the file is almost always fine and the response header is missing. Add AccessControlAllowOrigin: to every public discovery file, on…
174 OAuth Client Registrations on Our MCP Server: Only 60 Reached Consent
Direct answer: On our own MCP server, 174 OAuth clients registered themselves between 29 August and 18 November 2026, and 60 of them 34.5% ended with a person approving access. Every one of those 60…
