feat: add filter/search/pagination to MCP sessions list API

[Pratham-Mishra04]

Summary

The four MCP sessions list methods (ListAllOauthUserTokens, ListAllPendingOauthUserSessions, ListAllMCPPerUserHeaderCredentials, ListAllPendingMCPPerUserHeaderFlows) previously fetched all rows unconditionally and left all filtering to the handler. This PR pushes filtering down to SQL by introducing a shared MCPSessionsFilterParams struct and a reusable applyMCPSessionFilters helper, and adds server-side pagination to the merged sessions list endpoint.

Changes

• Renamed the four ListAll* store methods to List* and added a MCPSessionsFilterParams parameter to each. Filters for status, auth mode, MCP client ID, and a case-insensitive search string (matched against MCP client name/ID, user ID, session ID, and virtual key name/ID via LEFT JOIN) are now applied in SQL rather than in the handler.
• Introduced MCPSessionsFilterParams in store.go with documentation explaining why pagination is intentionally omitted from the struct (cross-table de-dup must happen before slicing).
• Added applyMCPSessionFilters in rdb.go as a shared helper that appends the WHERE clauses and search JOINs to a GORM query, parameterised by a mcpSessionFilterTable descriptor that carries the table name and the auth-mode column name (which differs between credential tables and flow tables).
• Qualified all ORDER BY and WHERE column references with their table names to avoid ambiguity after the search JOINs are added.
• Updated the list handler in mcp_sessions.go to parse query-string filters (q, status, auth_mode, mcp_client_id, kind, limit, offset) via a new parseMCPSessionsListQuery function, skip store calls that cannot contribute rows given the filter shape, perform a stable cross-table sort by created_at DESC after merging, and return a paginated response with count, total_count, limit, and offset fields.
• Added kindAllowed, flowsAllowed, and statusFilterAllowsPending helpers on mcpSessionsListQuery to cleanly express which store calls to skip.
• Updated MockConfigStore in config_test.go to match the new method signatures.
• Added rdb_mcp_sessions_test.go with integration-style tests covering no-filter listing, status/auth-mode/MCP-client-ID filtering, search by MCP client name, virtual key name, user ID, and session ID, preload population, and pending-only enforcement.
• Added mcp_sessions_test.go with unit tests for parseMCPSessionsListQuery covering defaults, all parameters, limit capping, invalid limit/offset values, and kindAllowed logic.

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

go test ./framework/configstore/... ./transports/bifrost-http/handlers/... ./transports/bifrost-http/lib/...

Validate filtering via the sessions endpoint:

# All sessions (default limit 50)
GET /api/mcp/sessions

# Filter by status and auth mode with pagination
GET /api/mcp/sessions?status=active,needs_reauth&auth_mode=vk&limit=25&offset=0

# Search by MCP client name
GET /api/mcp/sessions?q=GitHub

# Only token-kind rows
GET /api/mcp/sessions?kind=token

Expected: response includes sessions, count, total_count, limit, and offset fields; rows match the supplied filters; total_count reflects the full unsliced result.

Breaking changes

• Yes
• No

The four ListAll* store methods on the ConfigStore interface have been renamed and their signatures changed to accept MCPSessionsFilterParams. Any external implementations of ConfigStore must be updated to match the new signatures. The sessions list API response now includes additional pagination fields (count, total_count, limit, offset) alongside sessions.

Related issues

N/A

Security considerations

Search JOINs use parameterised LIKE queries; no raw user input is interpolated into SQL. Table and column names in applyMCPSessionFilters are hardcoded constants, not user-supplied. DAC scope enforcement remains at the ScopedDB(ctx) layer and is unaffected by this 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]

• feat: add filtering and pagination to MCP sessions table #3825
• feat: add filter/search/pagination to MCP sessions list API #3824 👈 (View in Graphite)
• feat: add can_reauth identity gate for user-mode MCP session rows #3823
• fix: mcp auth session UI improvements #3822
• dev

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

[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]

Warning

Review limit reached

@Pratham-Mishra04, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 24 minutes and 55 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bf381a32-2f4b-481a-a19f-3737806c2f24

📥 Commits

Reviewing files that changed from the base of the PR and between 358bc58 and 665483e.

📒 Files selected for processing (6)

• framework/configstore/rdb.go
• framework/configstore/rdb_mcp_sessions_test.go
• framework/configstore/store.go
• transports/bifrost-http/handlers/mcp_sessions.go
• transports/bifrost-http/handlers/mcp_sessions_test.go
• transports/bifrost-http/lib/config_test.go

📝 Walkthrough

Walkthrough

This PR adds MCPSessionsFilterParams and replaces four unparameterized ListAll* store methods with parameterized List* variants, implements shared RDB filtering/search JOINs, updates the /api/mcp/sessions handler to parse filters, gate store calls, merge and de-duplicate rows, sort deterministically, and return paginated responses; tests and mocks updated accordingly.

Changes

MCP Sessions Filterable Listing

Layer / File(s)	Summary
Filter parameter type and store interface updates framework/configstore/store.go	Adds exported MCPSessionsFilterParams and updates ConfigStore to replace four ListAll* methods with parameterized List* variants accepting the filter params.
RDB store method implementations with shared filtering framework/configstore/rdb.go	Implements ListOauthUserTokens, ListPendingOauthUserSessions, ListMCPPerUserHeaderCredentials, and ListPendingMCPPerUserHeaderFlows on RDBConfigStore; adds mcpSessionFilterTable and applyMCPSessionFilters to apply status/auth-mode/MCP-client filters and multi-column search via LEFT JOINs.
Store layer test fixture and comprehensive filter validation framework/configstore/rdb_mcp_sessions_test.go	Adds test setup and seed fixture (MCP client, virtual key, OAuth tokens/sessions, header credentials/flows) and validates listing APIs for no-filter, status/auth-mode/MCP-client filtering, multi-field search, MatchedUserIDs behavior, session-ID search, and association preloads.
HTTP handler query parsing and paginated cross-table merging transports/bifrost-http/handlers/mcp_sessions.go	Adds mcpSessionsListResponse, parseMCPSessionsListQuery with validation/capping and gating helpers, reworks handler to conditionally call filtered store methods, merges rows with de-duplication (suppress pending when active exists), filters deferred-fill flows, and stably sorts by CreatedAt.
Merged-result pagination and response shape transports/bifrost-http/handlers/mcp_sessions.go	Computes total_count, slices merged/sorted rows using offset/limit, and returns structured response with sessions, count, total_count, limit, and offset.
HTTP handler query parsing and validation tests transports/bifrost-http/handlers/mcp_sessions_test.go	Adds tests for default parsing, all supported query params, limit capping at max, invalid limit/offset producing HTTP 400, and kindAllowed behavior.
Test mock updates for signature alignment transports/bifrost-http/lib/config_test.go	Updates MockConfigStore to replace removed unparameterized list stubs with new parameterized methods accepting MCPSessionsFilterParams; stubs still return nil.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• maximhq/bifrost#3703: Introduces per-user header credential/flow storage and related listing logic that this PR builds upon.
• maximhq/bifrost#3705: Touches RDBConfigStore MCP/OAuth session logic and adds reconciliation hooks that are complementary to these listing changes.

Suggested reviewers

• akshaydeo
• danpiths

Poem

🐰 I hopped through tables, joins, and rows,
Tuned filters where the search breeze blows,
Merged and de-duped with careful art,
Paginated slices, tidy and smart—
Now sessions march in ordered rows.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add filter/search/pagination to MCP sessions list API' clearly and concisely summarizes the main changes in the PR.
Description check	✅ Passed	The PR description is comprehensive and covers all key sections: summary, detailed changes, type of change, affected areas, testing instructions, breaking changes documentation, security considerations, and completed checklist items.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 05-27-feat_adds_filters_for_mcp_session

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

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

[greptile-apps]

Confidence Score: 5/5

Safe to merge; all user input in SQL filters is parameterized, pagination and de-dup logic is correct, and the breaking interface change is contained to the ConfigStore boundary.

The filter-pushdown logic, cross-table de-dup, and pagination are all correct: flowsAllowed() and statusFilterAllowsPending() reliably gate the flow-table calls, the auth-mode filter is applied symmetrically across token and flow queries so de-dup remains consistent, and the stable sort on UTC RFC3339 strings produces deterministic pages. The search JOINs are only added when a search term is present and use hardcoded table/column names with parameterized LIKE values. Test coverage at both the store and handler layers is thorough.

No files require special attention.

Important Files Changed

Filename	Overview
framework/configstore/rdb.go	Four ListAll* methods renamed to List* with MCPSessionsFilterParams; applyMCPSessionFilters helper added with parameterized LIKE search and LEFT JOINs; ORDER BY and WHERE qualifications fixed for join safety.
transports/bifrost-http/handlers/mcp_sessions.go	list handler refactored to parse filter/pagination params, skip store calls by filter shape, merge and de-dup across four tables, stable-sort by created_at string before slicing, and return count/total_count/limit/offset in the response.
framework/configstore/store.go	MCPSessionsFilterParams struct added with well-documented fields; ConfigStore interface updated to new List* signatures.
framework/configstore/rdb_mcp_sessions_test.go	New integration-style tests covering no-filter listing, status/auth-mode/client-ID filtering, search by MCP client name, VK name, user ID, and session ID, MatchedUserIDs broadening, preload population, and pending-only enforcement.
transports/bifrost-http/handlers/mcp_sessions_test.go	New unit tests for parseMCPSessionsListQuery covering defaults, all params, limit capping, invalid limit/offset, and kindAllowed logic.
transports/bifrost-http/lib/config_test.go	MockConfigStore updated to match the renamed List* method signatures with MCPSessionsFilterParams; no logic changes.

_{Reviews (6): Last reviewed commit: "feat: adds filters for mcp session" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@framework/configstore/rdb_mcp_sessions_test.go`:
- Around line 183-193: The test
TestListOauthUserTokens_MatchedUserIDsIgnoredWhenSearchEmpty has the wrong
expected length: seedMCPSessionsFixture seeds 3 OAuth token rows and an empty
Search should return all rows; update the assertion for the result of
store.ListOauthUserTokens called with MCPSessionsFilterParams{MatchedUserIDs:
[]string{"user-42"}} to require.Len(t, got, 3) (replace the current 2) so the
test expectation matches the seeded fixture.

🪄 Autofix (Beta)

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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f3e574df-e2d5-4587-b966-eecf6ac843d5

📥 Commits

Reviewing files that changed from the base of the PR and between f3b68ca and 4618bc3.

📒 Files selected for processing (6)

• framework/configstore/rdb.go
• framework/configstore/rdb_mcp_sessions_test.go
• framework/configstore/store.go
• transports/bifrost-http/handlers/mcp_sessions.go
• transports/bifrost-http/handlers/mcp_sessions_test.go
• transports/bifrost-http/lib/config_test.go

🚧 Files skipped from review as they are similar to previous changes (5)

• framework/configstore/store.go
• transports/bifrost-http/handlers/mcp_sessions_test.go
• transports/bifrost-http/handlers/mcp_sessions.go
• transports/bifrost-http/lib/config_test.go
• framework/configstore/rdb.go

[Pratham-Mishra04]

Merge activity

• May 28, 7:29 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 28, 7:34 AM UTC: Graphite rebased this pull request as part of a merge.
• May 28, 7:35 AM UTC: @Pratham-Mishra04 merged this pull request with Graphite.