Conversation
…during registration means
Two gaps a self-hosted SCM POC hit in the field:
- cas.mdx listed no minimum gateway version. On 2.21.0 GET /oauth/<slug>/authorize
returns 500 {"message":"immutable"}, so the flow dies between client registration
and the CAS login page. Added as prerequisite 1 and a troubleshooting row.
- A client reporting "Dynamic Client Registration rejected (HTTP 401)" with
"Invalid API Key. Error Code: 03" is talking to the AI Gateway, not the MCP
Gateway, whose /oauth/register takes no API key. The troubleshooting page now
says how to tell the two apart, how to confirm from inside the pod, and the
base-URL / routing / unified-mode fixes. It also notes that unified mode keeps
/.well-known and /oauth at the root while servers move under /m.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Clarify unified-mode /m URLs and the gateway 2.22.0+ requirement.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 1
Open (1)
What changed in this PR
Documents MCP OAuth prerequisites and troubleshooting for self-hosted gateways.
Changes:
- Requires gateway 2.22.0+ for SCM CAS OAuth.
- Adds Error Code 03 registration diagnostics and routing checks.
- Clarifies unified-mode URL behavior.
| File | Summary |
|---|---|
aigw/product/mcp-gateway/authentication/cas.mdx |
Adds version requirements and OAuth troubleshooting entries. |
aigw/help-center/mcp-gateway-troubleshooting.mdx |
Adds registration diagnostics and deployment guidance. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| 3. **Set `MCP_GATEWAY_BASE_URL`** to your public gateway URL (for example `https://<your-gateway-host>`). The gateway uses this to construct callback and discovery URLs—if it's wrong, OAuth and discovery fail. | ||
| 4. Make sure your ingress forwards the `Host` header so the server advertises its public URL (not an internal address). | ||
|
|
||
| With `SERVER_MODE=unified` (gateway 2.20.0 or later), both gateways share one port: MCP servers are at `https://<your-gateway-host>/m/{slug}/mcp`, while `/.well-known/*` and `/oauth/*` stay at the root, not under `/m`. |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A self-hosted SCM POC (AKS, CIE with Entra ID, gateway 2.21.0) couldn't get MCP OAuth 2.1 working: API-key access worked, and OAuth failed before any login page opened. Two things in the docs would have let them fix it themselves.
Changes
aigw/product/mcp-gateway/authentication/cas.mdxGET /oauth/<slug>/authorizereturns500 {"status":"failure","message":"immutable"}, so the flow stops between client registration and the CAS login page. 2.22.0 fixed it (see the 2026-09-11 changelog entry).Error Code: 03registration failure below.aigw/help-center/mcp-gateway-troubleshooting.mdx/.well-known/*,/oauth/registerandOPTIONSneed no API key, and its own rejection is{"error":"unauthorized"}withWWW-Authenticate. The section gives three checks (discovery URLs, a test registration, the same request from inside the pod) and the fixes:MCP_GATEWAY_BASE_URL, routing every path on the MCP host to8788underSERVER_MODE=all, orSERVER_MODE=unified./m, discovery and OAuth at the root. Only the changelog mentioned this before, and it reads as if everything moves under/m.How this was verified
Against a live self-hosted gateway (
gateway_enterprise, unified mode), with no API key on any request:GET /.well-known/oauth-authorization-serverOPTIONS /oauth/registerPOST /oauth/registerAuthorizationorx-portkey-api-key)GET /oauth/<slug>/authorizeimmutablecloud-auth.us.apps.paloaltonetworks.comInvalid API Key. Error Code: 03Not verified:
SERVER_MODE=mcp/allon8788. The in-pod check in the new section is there to tell a routing fault from a mode-specific one.Checks
mint validatepasses.mint broken-links --check-anchorsflags nothing new; the three anchors it reports on the troubleshooting page are pre-existing and also appear on the non-aigw copy.🤖 Generated with Claude Code