docs: add conflicting credentials troubleshooting and clarify MCP auth mode credential exclusivity

[Pratham-Mishra04]

Summary

Improves documentation around MCP gateway auth edge cases, particularly the conflicting credentials error and stale cached token behavior in Claude Code, and fixes a minor label inconsistency in the OAuth consent UI.

Changes

• Rewrites the Method Not Allowed troubleshooting entry to clarify that switching to both/oauth mode resolves the Re-authenticate error, and that headers mode users should use Reconnect instead.
• Adds a new troubleshooting accordion for the Got new credentials, but bifrost rejected them on reconnect error, covering two root causes: stale cached OAuth state after switching auth modes, and Claude Code sending both an OAuth token and a VK header simultaneously in both mode when the VK is configured under x-bf-vk or X-Api-Key.
• Adds a Note callout advising users to remove and re-add the MCP server after any auth settings change, since Claude Code caches tokens per server and stale credentials can survive Reconnect.
• Documents in gateway-auth.mdx that /mcp requires exactly one credential type per request — sending an OAuth token alongside a header credential is rejected with conflicting credentials even in both mode.
• Adds a Conflicting credentials on /mcp troubleshooting entry to gateway-auth.mdx with symptom, cause, and fix.
• Fixes the OAuth consent page label from "API key" to "Virtual Key" for consistency with Bifrost terminology.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Review the updated troubleshooting sections in docs/cli-agents/claude-code.mdx and docs/mcp/gateway-auth.mdx. To validate the conflicting credentials behavior:

1. Configure Bifrost in both mode with a VK set under x-bf-vk or X-Api-Key.
2. Connect Claude Code and complete the OAuth flow.
3. Confirm the conflicting credentials error is returned.
4. Reconfigure the VK as Authorization: Bearer <vk> or remove it, reconnect, and confirm the error is gone.

Breaking changes

• Yes
• No

Related issues

anthropics/claude-code#46640

Security considerations

No new auth logic introduced. The documentation clarifies existing behavior around credential handling to prevent misconfiguration where two credential types are inadvertently sent together.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Pratham-Mishra04]

• docs: add conflicting credentials troubleshooting and clarify MCP auth mode credential exclusivity #4910 👈 (View in Graphite)
• docs: clarify adaptive load balancing weight calculation and cross-node coordination #4744
• docs: update benchmarking docs for new CLI flags, mocker/hitter tools, and revised result schema #4909
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation clarifies Claude Code MCP gateway auth troubleshooting for parse errors, credential conflicts, and cached credentials, while the OAuth consent page text is updated for the VK option.

Changes

MCP Auth Documentation Updates

Layer / File(s)	Summary
Claude Code MCP FAQ updates docs/cli-agents/claude-code.mdx	Reworks the auth parse-error FAQ, adds a new FAQ on rejected credentials after reconnect, and adds a note on clearing cached MCP server credentials after auth mode changes.
Gateway-auth conflicting credentials docs docs/mcp/gateway-auth.mdx	Documents the single-credential-type requirement for /mcp requests and adds a troubleshooting section for the "conflicting credentials" error.

OAuth Consent Page Text Update

Layer / File(s)	Summary
VK option label update ui/app/oauth/consent/page.tsx	Changes the VK option description text to reference "Virtual Key" instead of "API key".

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• maximhq/bifrost#3882: Both PRs update the Claude Code MCP Gateway FAQ/troubleshooting accordions in docs/cli-agents/claude-code.mdx.
• maximhq/bifrost#4522: Both PRs update the same MCP gateway auth documentation clarifying /mcp auth behavior across mcp_server_auth_mode settings.
• maximhq/bifrost#4510: Both PRs update MCP OAuth/consent behavior and the related Virtual Key wording in the consent flow.

Suggested reviewers: akshaydeo, danpiths

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately summarizes the main doc changes around conflicting credentials and MCP auth mode behavior.
Description check	✅ Passed	The description follows the template closely and covers summary, changes, testing, affected areas, security, and related issues.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 07-04-docs_mcp_auth_doc_updates

---

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

[greptile-apps]

Confidence Score: 5/5

Safe to merge — documentation and a cosmetic UI label change with no runtime logic affected.

All three changed files are documentation or a one-word UI label fix. The error message quoted in the troubleshooting entries matches the actual strings in mcpserver.go, the data-testid attributes on the consent page are unchanged, and no Go code or auth logic was modified.

No files require special attention.

Important Files Changed

Filename	Overview
docs/cli-agents/claude-code.mdx	Rewrites the 405 accordion entry, adds a new accordion for the "rejected on reconnect" error covering both stale-token and conflicting-credential root causes, and appends a Note callout about removing/re-adding the server after auth changes.
docs/mcp/gateway-auth.mdx	Adds a one-credential-per-request constraint paragraph to the mode table, and appends a "Conflicting credentials on /mcp" troubleshooting entry with symptom, cause, and fix. Prose aligns with actual error messages in mcpserver.go.
ui/app/oauth/consent/page.tsx	Capitalises "Virtual Key" in the section title and updates the description from "API key" to "Virtual Key"; data-testid attributes are preserved.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Client connects to /mcp] --> B{mcp_server_auth_mode?}
    B -->|headers| C[Header credential only]
    B -->|oauth| D[Bifrost JWT only]
    B -->|both| E{Credential type sent?}
    E -->|Header VK only| F[Accepted]
    E -->|OAuth token only| G[Accepted]
    E -->|Both at once| H[conflicting credentials error]
    C --> I{Valid VK/API key?}
    I -->|Yes| J[Request proceeds]
    I -->|No| K[401 Unauthorized]
    D --> L{Valid Bifrost JWT?}
    L -->|Yes| J
    L -->|No| K
    F --> J
    G --> J

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Client connects to /mcp] --> B{mcp_server_auth_mode?}
    B -->|headers| C[Header credential only]
    B -->|oauth| D[Bifrost JWT only]
    B -->|both| E{Credential type sent?}
    E -->|Header VK only| F[Accepted]
    E -->|OAuth token only| G[Accepted]
    E -->|Both at once| H[conflicting credentials error]
    C --> I{Valid VK/API key?}
    I -->|Yes| J[Request proceeds]
    I -->|No| K[401 Unauthorized]
    D --> L{Valid Bifrost JWT?}
    L -->|Yes| J
    L -->|No| K
    F --> J
    G --> J

Loading

_{Reviews (2): Last reviewed commit: "docs: mcp auth doc updates" | Re-trigger Greptile}

[akshaydeo]

Merge activity

• Jul 4, 4:52 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 4, 4:55 PM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.