docs: add needs_session_stickiness field, session stickiness behavior, and per-call vs sticky connection docs - #5974
Conversation
|
|
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe MCP documentation now defines ChangesMCP session stickiness
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Merge activity
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/mcp/auth/headers.mdx`:
- Line 103: Scope the per-call default wording to HTTP clients in
docs/mcp/auth/headers.mdx lines 103-103 by prefixing it with “For HTTP header
clients” while retaining the Session Stickiness link; apply the equivalent “For
HTTP OAuth clients” prefix in docs/mcp/auth/oauth.mdx lines 167-167, also
retaining that link.
In `@docs/mcp/connecting-to-servers.mdx`:
- Line 76: Update the sticky connection row to make recovery client-specific:
direct OAuth clients to use admin reauthorize, instruct headers clients to
update their stored headers, and avoid prescribing a recovery action for none
clients. Verify the guidance matches the documented client behavior and config
schema.
In `@docs/openapi/schemas/management/mcp.yaml`:
- Around line 197-207: The create schema currently permits
needs_session_stickiness: false for non-HTTP connection types, despite server
validation rejecting it. Update the schema constraint around
needs_session_stickiness to require connection_type: http when the field is
explicitly false, while preserving default: false only on the HTTP create
subtype so SSE and STDIO schemas do not generate that value.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 4ed79cbd-e1b8-40b5-bb24-af143f864b9c
📒 Files selected for processing (5)
docs/deployment-guides/config-json/schema-reference.mdxdocs/mcp/auth/headers.mdxdocs/mcp/auth/oauth.mdxdocs/mcp/connecting-to-servers.mdxdocs/openapi/schemas/management/mcp.yaml
| </Tab> | ||
| </Tabs> | ||
|
|
||
| By default this connection is per-call (a fresh connection per tool call, no shared upstream connection to keep alive) — see [Session Stickiness](../connecting-to-servers#session-stickiness-http-only) to make it sticky instead. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Scope the per-call default to HTTP.
Both pages also support SSE, which remains sticky regardless of this setting.
docs/mcp/auth/headers.mdx#L103-L103: Prefix the statement with “For HTTP header clients” and retain the Session Stickiness link.docs/mcp/auth/oauth.mdx#L167-L167: Prefix the statement with “For HTTP OAuth clients” and retain the Session Stickiness link.
As per path instructions, “Check docs for parity with code, config.schema.json, and provider behavior.”
📍 Affects 2 files
docs/mcp/auth/headers.mdx#L103-L103(this comment)docs/mcp/auth/oauth.mdx#L167-L167
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/mcp/auth/headers.mdx` at line 103, Scope the per-call default wording to
HTTP clients in docs/mcp/auth/headers.mdx lines 103-103 by prefixing it with
“For HTTP header clients” while retaining the Session Stickiness link; apply the
equivalent “For HTTP OAuth clients” prefix in docs/mcp/auth/oauth.mdx lines
167-167, also retaining that link.
Source: Path instructions
|
|
||
| | Value | Behavior | | ||
| | --- | --- | | ||
| | `true` | **Sticky.** One shared connection is opened once and reused for every tool call, with an automatic health-checked reconnect on failure. Lower per-call latency; if the connection's credential dies, the client needs an admin `reauthorize` to recover. | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Make the sticky recovery action auth-specific.
This row applies to headers and none clients, but reauthorize only applies to shared OAuth clients. For headers, instruct users to update the stored headers. Do not prescribe reauthorize for none.
As per path instructions, “Check docs for parity with code, config.schema.json, and provider behavior.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/mcp/connecting-to-servers.mdx` at line 76, Update the sticky connection
row to make recovery client-specific: direct OAuth clients to use admin
reauthorize, instruct headers clients to update their stored headers, and avoid
prescribing a recovery action for none clients. Verify the guidance matches the
documented client behavior and config schema.
Source: Path instructions
| needs_session_stickiness: | ||
| type: boolean | ||
| default: false | ||
| description: | | ||
| HTTP-only. Only meaningful for auth_type "oauth", "headers", or "none" | ||
| (a server-level connection) — per-user auth types are always per-call | ||
| regardless of this field. When true, Bifrost holds one persistent | ||
| upstream connection, reused for every tool call. When false or | ||
| omitted (the default), a fresh connection is dialed per tool call. | ||
| Cannot be set to false for connection_type "sse" or "stdio" — both | ||
| are always sticky. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Enforce the HTTP-only restriction in the create schema.
MCPClientCreateRequestSSE and MCPClientCreateRequestSTDIO inherit this field and currently accept needs_session_stickiness: false. The server rejects that value unless connection_type is http.
Add an if/then constraint that requires connection_type: http when this field is explicitly false. Keep the default: false annotation on the HTTP create subtype so generated SSE and STDIO forms do not prefill a rejected value.
As per path instructions, “Check docs for parity with code, config.schema.json, and provider behavior.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/openapi/schemas/management/mcp.yaml` around lines 197 - 207, The create
schema currently permits needs_session_stickiness: false for non-HTTP connection
types, despite server validation rejecting it. Update the schema constraint
around needs_session_stickiness to require connection_type: http when the field
is explicitly false, while preserving default: false only on the HTTP create
subtype so SSE and STDIO schemas do not generate that value.
Source: Path instructions
71bc16e to
33214a2
Compare
2 participants
Summary
Documents the new
needs_session_stickinessfield for HTTP MCP client configurations, which controls whether Bifrost holds a single persistent upstream connection or opens a fresh connection per tool call.Changes
needs_session_stickinessto the schema reference table with a full description of its behavior, constraints, and relationship to auth types and connection types.config.jsonusage examples.headersandoauthauth pages, linking to the new session stickiness section.needs_session_stickinessto bothMCPClientCreateRequestBaseandMCPClientUpdateRequestin the OpenAPI schema with full field descriptions.The field is only meaningful for server-level auth types (
oauth,headers,none) on HTTP connections. SSE and STDIO connections are always sticky by nature, and settingneeds_session_stickiness: falseon either is rejected. Per-user auth types are always per-call regardless of this field.Type of change
Affected areas
How to test
Review the rendered documentation for:
needs_session_stickinessrow in the schema reference table atdocs/deployment-guides/config-json/schema-reference.mdxdocs/mcp/connecting-to-servers.mdx, including the behavior table and all three tabs (Web UI, API, config.json)headersandoauthauth pagesVerify that the OpenAPI schema descriptions for
needs_session_stickinessare accurate in both the create and update request objects.Breaking changes
Related issues
Security considerations
None. This field controls connection lifecycle behavior only and does not affect credential handling or secret exposure.
Checklist
docs/contributing/README.mdand followed the guidelines