feat: add pagination and filtering to MCP clients list endpoint

[impoiler]

Summary

The GET /management/mcp/clients endpoint has been upgraded from returning a flat array to a paginated response with filtering and search support. The is_deprecated field has also been removed from model schemas, and a new disable_vk_identity option has been added to the MCP server OAuth configuration.

Changes

• Paginated MCP clients list: The getMCPClients endpoint now returns a MCPClientsListResponse object containing clients, count, total_count, limit, and offset fields instead of a bare array.
• Query parameters for filtering: Added limit, offset, search, server, connection_type, auth_type, state, all_virtual_keys, virtual_keys, code_mode, and disabled query parameters to the endpoint. Multi-value filters use comma-separated OR semantics.
• 400 error response: Added a BadRequest response to the getMCPClients endpoint for invalid query parameters.
• Removed is_deprecated field: Dropped the is_deprecated boolean from model schemas in both inline path definitions and the shared MCPClient component schema.
• disable_vk_identity option: Added a new boolean field to the MCP server OAuth configuration that forces identity-provider login by removing virtual-key identity from the consent flow and rejecting existing virtual-key-mode grants.
• New MCPClientsListResponse schema: Introduced a reusable schema definition for the paginated clients list response.

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

Verify the updated OpenAPI spec is valid and that the getMCPClients endpoint reflects the new paginated contract:

# Validate the OpenAPI spec
npx @redocly/cli lint docs/openapi/openapi.json

# Confirm pagination fields are present in the response schema
curl -s -H "Authorization: Bearer <token>" \
  "https://<host>/management/mcp/clients?limit=10&offset=0&search=my-client" | \
  jq '{count: .count, total_count: .total_count, limit: .limit, offset: .offset}'

# Confirm filtering works
curl -s -H "Authorization: Bearer <token>" \
  "https://<host>/management/mcp/clients?connection_type=http,sse&disabled=false"

New config field — disable_vk_identity:

• Only meaningful when mcp_server_auth_mode is oauth and an identity provider is configured.
• When true, virtual-key identity is removed from the consent flow and existing virtual-key-mode grants are rejected at /mcp and denied on refresh.

Breaking changes

• Yes
• No

The getMCPClients response shape has changed from an array to a paginated object. Callers that previously iterated directly over the response array must now access .clients instead.

Related issues

Security considerations

The new disable_vk_identity flag enforces identity-provider login for MCP OAuth flows, preventing virtual-key credentials from being used as a substitute for user identity. This strengthens the authentication posture for deployments that require explicit IdP-backed user consent.

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

[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: 785f62e8-8f9d-4442-a7df-23a602cda955

📥 Commits

Reviewing files that changed from the base of the PR and between 3317861 and a5faed7.

📒 Files selected for processing (3)

• docs/openapi/openapi.json
• docs/openapi/paths/management/mcp.yaml
• docs/openapi/schemas/management/mcp.yaml

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

• docs/openapi/schemas/management/mcp.yaml
• docs/openapi/paths/management/mcp.yaml
• docs/openapi/openapi.json

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Updated the MCP clients list endpoint to support pagination and richer querying, including name search and filtering by server, connection/auth type, state, virtual keys, code mode, and enabled/disabled status.
  • The successful response is now a paginated payload containing clients plus count, total_count, limit, and offset.
• Documentation
  • Expanded consent-flow documentation for disable_vk_identity, including grant/refresh denial behavior and when it applies.
  • Added documentation for 400 (BadRequest) responses for invalid queries.
  • Removed is_deprecated from the published schema documentation.

Walkthrough

This PR updates OpenAPI documentation for getMCPClients, adding pagination and filtering query parameters, a new paginated response schema, and mirrored bundled spec changes. It also adjusts several unrelated schema descriptions and removes repeated is_deprecated fragments.

Changes

MCP clients endpoint documentation update

Layer / File(s)	Summary
New paginated response schema docs/openapi/schemas/management/mcp.yaml	Adds MCPClientsListResponse with required clients, count, total_count, limit, and offset fields, with clients referencing MCPClient.
Endpoint query params and response reference docs/openapi/paths/management/mcp.yaml, docs/openapi/openapi.json	Expands getMCPClients with pagination and filtering query parameters, changes the 200 response to the paginated schema, and adds a 400 BadRequest response.
Bundled openapi.json sync docs/openapi/openapi.json	Removes repeated is_deprecated fragments, expands disable_vk_identity descriptions in two locations, and applies the final document adjustment.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• maximhq/bifrost#4767: Shares the same getMCPClients listing surface and paginated response shape updates.
• maximhq/bifrost#4522: Uses the mcp_server_auth_mode context referenced by the updated disable_vk_identity description.

Suggested reviewers: akshaydeo, danpiths

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding pagination and filtering to the MCP clients list endpoint.
Description check	✅ Passed	The description covers the required summary, changes, testing, breaking change, security, and affected areas sections.
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-feat_mcp_clients_filters_support_for_public_apis

---

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

[impoiler]

• feat: add pagination and filtering to MCP clients list endpoint #4841 👈 (View in Graphite)
• feat: add filter sidebar with faceted filtering to MCP clients page #4840
• feat: add connection_type, auth_type, state, and virtual_key filters to MCP clients list #4839
• dev

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

[greptile-apps]

Confidence Score: 4/5

Safe to merge after resolving the model is_deprecated spec mismatch; the pagination and filtering additions are well-structured.

The is_deprecated field is removed from model response schemas in the spec, but ModelResponse and ModelDetailsResponse in providers.go still serialize it via omitempty. Any deployment that has deprecated models will produce responses that diverge from the spec, breaking code generators and strict validators.

docs/openapi/openapi.json — the is_deprecated removal needs to be reconciled with the implementation in transports/bifrost-http/handlers/providers.go. docs/openapi/openapi.yaml — MCPClientsListResponse should be registered in components/schemas for consistency with other named MCP schemas.

Important Files Changed

Filename	Overview
docs/openapi/openapi.json	Adds paginated getMCPClients response schema (inlined) and disable_vk_identity config field; removes is_deprecated from model response schemas despite the Go handlers still serializing the field when set.
docs/openapi/paths/management/mcp.yaml	Upgrades getMCPClients to a paginated response with 11 new query parameters; previously flagged issues (state enum constraint, limit minimum) have been corrected in this revision.
docs/openapi/schemas/management/mcp.yaml	Adds MCPClientsListResponse reusable schema with correct required fields and pagination fields; not yet registered in openapi.yaml components so the bundler inlines it instead of promoting it to a named component.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant Handler as GET /management/mcp/clients
    participant Engine as MCP Engine

    Client->>Handler: "GET ?limit=25&offset=0&search=foo&connection_type=http,sse&disabled=false"
    Note over Handler: Parse & validate query params<br/>(limit 1-100, offset >= 0,<br/>comma-separated OR filters)
    Handler->>Engine: getMCPClientsPaginated(params)
    Engine-->>Handler: []MCPClient (filtered + paginated)
    Handler-->>Client: "MCPClientsListResponse { clients[], count, total_count, limit, offset }"

    alt Invalid params
        Client->>Handler: "GET ?limit=999"
        Handler-->>Client: 400 BifrostError
    end

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"}}}%%
sequenceDiagram
    participant Client
    participant Handler as GET /management/mcp/clients
    participant Engine as MCP Engine

    Client->>Handler: "GET ?limit=25&offset=0&search=foo&connection_type=http,sse&disabled=false"
    Note over Handler: Parse & validate query params<br/>(limit 1-100, offset >= 0,<br/>comma-separated OR filters)
    Handler->>Engine: getMCPClientsPaginated(params)
    Engine-->>Handler: []MCPClient (filtered + paginated)
    Handler-->>Client: "MCPClientsListResponse { clients[], count, total_count, limit, offset }"

    alt Invalid params
        Client->>Handler: "GET ?limit=999"
        Handler-->>Client: 400 BifrostError
    end

Loading

_{Reviews (5): Last reviewed commit: "feat_mcp_clients_filters_support_for_pub..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🤖 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/openapi/openapi.json`:
- Around line 38078-38087: The OpenAPI definition for the query parameter named
limit is inconsistent with its description and should be aligned. Update the
limit schema in the OpenAPI spec so it matches the documented behavior in the
parameter entry: set the minimum to 1 instead of 0, and add the default value of
25 to the schema. Keep the description and schema parity consistent for the
limit field so generated docs and clients reflect the same bounds and default.

In `@docs/openapi/paths/management/mcp.yaml`:
- Around line 87-93: The `limit` query parameter in the MCP OpenAPI spec has a
schema that conflicts with its description. Update the parameter definition in
the management MCP path so the schema matches “1–100, default 25”: change the
minimum to 1 and add a schema default of 25. Keep the definition aligned in the
`limit` parameter block so generated clients and validation reflect the
documented behavior.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4ddd4e5f-daaa-4daa-85ee-9fce43e35998

📥 Commits

Reviewing files that changed from the base of the PR and between b186756 and 745fe87.

📒 Files selected for processing (3)

• docs/openapi/openapi.json
• docs/openapi/paths/management/mcp.yaml
• docs/openapi/schemas/management/mcp.yaml

[Pratham-Mishra04]

Merge activity

• Jul 2, 10:09 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 2, 10:14 AM UTC: Graphite rebased this pull request as part of a merge.
• Jul 2, 10:15 AM UTC: @Pratham-Mishra04 merged this pull request with Graphite.

The base branch was changed.