docs: clarify two-layer token refresh behavior and disabled-client refresh token expiry

[Pratham-Mishra04]

Summary

Documents the two-layer automatic token refresh behavior in Bifrost's OAuth flow, clarifying how background refresh and on-use refresh work together, and what happens when an MCP client is disabled.

Changes

• Expanded the "Automatic refresh" section to describe both the background worker (proactive refresh before expiry) and the inline fallback (refresh on first use after expiry)
• Added a note explaining that background refresh is paused when a client is disabled, and that re-authorization may be required if the provider expires the idle refresh token during that time
• Added a corresponding troubleshooting bullet under the "Token refresh fails" accordion to surface this as a known cause of expired token errors

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 rendered docs to confirm the updated "Automatic refresh" section and troubleshooting accordion entry are accurate and clearly worded.

Breaking changes

• Yes
• No

Related issues

Security considerations

None. This is a documentation-only change.

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

[Pratham-Mishra04]

• docs: clarify two-layer token refresh behavior and disabled-client refresh token expiry #4849 👈 (View in Graphite)
• fix: skip background token refresh for disabled/unconfigured MCP clients and guarantee non-nil logger in sync workers #4848
• dev

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

[greptile-apps]

Confidence Score: 5/5

Documentation-only change with no code modifications; safe to merge.

The prose accurately reflects the implementation: GetExpiringOauthTokens in framework/configstore/rdb.go joins against config_mcp_clients and filters out disabled clients, confirming the background refresh pauses while the client is disabled claim, and GetAccessToken in framework/oauth2/main.go performs the inline refresh described as the on-use layer. The docs.json navigation entry for this page already exists.

No files require special attention.

Important Files Changed

Filename	Overview
docs/mcp/auth/oauth.mdx	Expands Automatic refresh section to document the two-layer (background worker + inline fallback) refresh mechanism and adds a troubleshooting bullet for tokens that expire while a client is disabled. Verified against framework/oauth2/sync.go and framework/configstore/rdb.go — the claims are accurate.

_{Reviews (3): Last reviewed commit: "docs: mcp refresh token updates docs" | Re-trigger Greptile}

[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.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d4338fc1-1f80-4e69-a3f7-ba300c90d0fa

📥 Commits

Reviewing files that changed from the base of the PR and between ecd3323 and f3b687c.

📒 Files selected for processing (1)

• docs/mcp/auth/oauth.mdx

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Clarified how OAuth token refresh works for MCP server admin-side authentication.
  • Explained that refresh can happen proactively in the background or immediately when a request uses an expired token.
  • Added guidance that background refresh only runs while the MCP client is enabled, and long disablement may require re-authorization.
  • Expanded troubleshooting tips for oauth token expired errors with a new check for extended client downtime.

Walkthrough

This PR updates the MCP OAuth documentation to clarify token refresh behavior, describing background proactive refresh and inline on-use refresh, noting that background refresh pauses when the client is disabled, and adding a related troubleshooting note.

Changes

OAuth refresh documentation update

Layer / File(s)	Summary
Automatic refresh and troubleshooting clarifications docs/mcp/auth/oauth.mdx	Rewrites the "Automatic refresh" section to explain background proactive refresh vs. inline refresh on expiry, adds enable/disable semantics, and adds a troubleshooting bullet about refresh token expiry during long disablement.

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

Possibly related PRs

• maximhq/bifrost#3706: Both PRs update the same MCP OAuth documentation covering token refresh and troubleshooting concepts.
• maximhq/bifrost#4807: Both PRs modify the "Automatic refresh" section of the same OAuth doc file.

Suggested reviewers: akshaydeo, danpiths

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the PR’s main documentation change about OAuth token refresh behavior and disabled-client expiry.
Description check	✅ Passed	The description follows the repository template well, covering summary, changes, type, affected areas, testing, breaking changes, issues, security, and checklist.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 07-02-docs_mcp_refresh_token_updates_docs

---

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

[Pratham-Mishra04]

Merge activity

• Jul 2, 1:44 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 2, 1:47 PM UTC: Graphite rebased this pull request as part of a merge.
• Jul 2, 1:48 PM UTC: @Pratham-Mishra04 merged this pull request with Graphite.

The base branch was changed.