---
title: "Fix \"Issuer Mismatch\" in OAuth Authorization Server Metadata (RFC 8414 §3.3) on Your MCP Server"
slug: oauth-issuer-mismatch-rfc-8414-fix
published: 2026-11-15T13:12:31.546556+00:00
updated: 2026-11-15T13:12:31.546556+00:00
author: "M Asif Rahman"
author_url: https://ar.bd
category: "AI Readiness"
tags: MCP, OAuth, RFC 8414, authorization server metadata, check:P4
description: "Fix the MCP \"issuer mismatch\" error: four causes of an RFC 8414 §3.3 failure, a seven-case SDK lab, and a 30-line checker that compares the three strings."
url: https://aiscan.site/blog/oauth-issuer-mismatch-rfc-8414-fix
---

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](https://www.rfc-editor.org/rfc/rfc8414.html#section-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](https://www.rfc-editor.org/rfc/rfc8414.html#section-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)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), 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:

```text
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.

1. Stop serving `/.well-known/oauth-authorization-server` from your MCP host.
2. In `/.well-known/oauth-protected-resource`, set `"authorization_servers": ["<the IdP's issuer, copied from its own metadata>"]`.
3. 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](https://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](https://aiscan.site/docs/checks/capabilities) 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:

```python
#!/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:

```text
$ 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`:

```bash
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 `issuer` to 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](https://aiscan.site/blog/oauth-discovery-for-agents). If the protected-resource file itself is at the wrong path, read [the protected-resource path fix](https://aiscan.site/blog/mcp-protected-resource-metadata-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](https://aiscan.site/blog/oauth-discovery-metadata-adoption-corpus).

## Your next step

Scan your site at [aiscan.site](https://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](https://aiscan.site/guides).

