docs(auth): add initial SEP-991 impact assessment

[Aditya7880900936]

Summary

Adds an initial investigation document for issue #396 to assess the impact of SEP-991 (OAuth Client ID Metadata Documents) on MCP Gateway authentication flows, examples, and documentation.

Findings

• Current documentation assumes Dynamic Client Registration (DCR) as part of the recommended OAuth flow.
• SEP-991 changes the preferred registration mechanism from DCR to Client ID Metadata Documents (CIMD).
• Protected Resource Metadata discovery appears unaffected.
• Authentication examples, diagrams, and design documents may require updates.

Follow-up Investigation

• Evaluate Keycloak support for Client ID Metadata Documents.
• Determine whether examples should continue using DCR, adopt CIMD, or support both.
• Propose documentation updates based on compatibility findings.

Related to #396

Summary by CodeRabbit

• Documentation
  • Added design documentation assessing SEP-991 impact on MCP Gateway authentication design.
  • Analyzes implications of OAuth Client ID Metadata Documents on current authentication architecture.
  • Identifies documentation requiring updates and documents ongoing investigation with key open questions and recommended directions.

[coderabbitai]

📝 Walkthrough

Walkthrough

New design document assessing SEP-991's impact on MCP Gateway authentication. Covers current DCR-based assumptions, CIMD shift mechanics, documentation alignment needs, Keycloak compatibility questions, and recommended investigation directions.

Changes

SEP-991 Impact Assessment

Layer / File(s)	Summary
SEP-991 impact assessment and design investigation docs/design/sep-991-impact-analysis.md	Design investigation document analyzing how SEP-991 shifts authentication from DCR to URL-based client IDs with metadata documents, assesses current documentation and implementation alignment, enumerates review checklist, documents open questions (Keycloak support), and outlines investigation status and recommended directions.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested labels

review-effort/small

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a design document assessing SEP-991's impact on MCP Gateway authentication.
Linked Issues check	✅ Passed	The PR addresses the primary objectives of issue #396 by providing initial investigation into SEP-991 impact, clarifying CIMD concepts, and identifying open questions including Keycloak compatibility.
Out of Scope Changes check	✅ Passed	The PR contains only the investigation document directly addressing issue #396; all content relates to assessing SEP-991 impact on authentication design.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[david-martin]

Hi @Aditya7880900936, thanks for putting this together.

A couple of things:

First, could you update the PR description to remove "Fixes #396"? The investigation and design doc for that issue still has more ground to cover (the follow-up items you listed here, for example), so we would want to keep the issue open.

Second, are you planning to continue progressing this investigation further, or would you prefer to land what is here and leave the remaining work for someone else to pick up?

Either way is fine, just want to understand your intent so we can plan accordingly.

[Aditya7880900936]

Hi @david-martin,

Thanks for the review. I've updated the PR description and removed the issue-closing reference.

Yes, I'd like to continue working on this investigation. My intention with this PR was to capture the initial findings and establish a starting point for the discussion.

I'd appreciate any guidance on the preferred next steps. In particular, if there are specific areas you'd like me to focus on next, or any recommendations on how you'd like the remaining investigation to be approached, I'd be happy to continue contributing.