Skip to content

feat: add pagination and filtering to MCP clients list endpoint #4841

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pratham-Mishra04 merged 1 commit into from
Jul 2, 2026
+254 −21
Merged

feat: add pagination and filtering to MCP clients list endpoint #4841

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 152 additions & 17 deletions docs/openapi/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37001,10 +37001,6 @@
"provider": {
"type": "string"
},
"is_deprecated": {
"type": "boolean",
"description": "True when the model is marked deprecated in the Bifrost pricing datasheet. Deprecated models remain listable for migration and compatibility workflows."
},
"accessible_by_keys": {
"type": "array",
"items": {
Expand Down Expand Up @@ -37153,10 +37149,6 @@
}
}
},
"is_deprecated": {
"type": "boolean",
"description": "True when the model is marked deprecated in the Bifrost pricing datasheet. Deprecated models remain listable for migration and compatibility workflows."
},
"accessible_by_keys": {
"type": "array",
"items": {
Expand Down Expand Up @@ -38078,10 +38070,107 @@
"get": {
"operationId": "getMCPClients",
"summary": "List MCP clients",
"description": "Returns a list of all configured MCP clients with their tools and connection state.",
"description": "Returns a paginated list of configured MCP clients with their tools and connection state.\nSupports case-insensitive name search and exact-match filtering by connection type, auth type,\ncode-mode, and enabled/disabled status. Multi-value filters accept a comma-separated list and\nuse OR semantics within a field.\n",
"tags": [
"MCP"
],
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Maximum number of clients to return (1–100, default 25).",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
Comment thread
coderabbitai[bot] marked this conversation as resolved.
{
"name": "offset",
"in": "query",
"description": "Number of clients to skip.",
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"name": "search",
"in": "query",
"description": "Case-insensitive search by client name.",
"schema": {
"type": "string"
}
},
{
"name": "server",
"in": "query",
"description": "Filter to a single client by its exact client_id.",
"schema": {
"type": "string"
}
},
{
"name": "connection_type",
"in": "query",
"description": "Comma-separated connection types to include (OR semantics).",
"schema": {
"type": "string",
"example": "http,sse"
}
},
{
"name": "auth_type",
"in": "query",
"description": "Comma-separated auth types to include (OR semantics).",
"schema": {
"type": "string",
"example": "oauth,per_user_oauth"
}
},
{
"name": "state",
"in": "query",
"description": "Comma-separated runtime connection states to include (OR semantics),\nresolved against live engine state. `connected` matches clients the engine\ncurrently reports as connected; `disconnected` matches everything else.\n",
"schema": {
"type": "string",
"example": "connected"
}
},
{
"name": "all_virtual_keys",
"in": "query",
"description": "When true, include clients that are open to all virtual keys (allow_on_all_virtual_keys). ORs with virtual_keys.",
"schema": {
"type": "boolean"
}
},
{
"name": "virtual_keys",
"in": "query",
"description": "Comma-separated virtual key IDs; includes clients explicitly assigned to any of them. ORs with all_virtual_keys.",
"schema": {
"type": "string"
}
},
{
"name": "code_mode",
"in": "query",
"description": "Filter by code-mode clients. Omit for no filter.",
"schema": {
"type": "boolean"
}
},
{
"name": "disabled",
"in": "query",
"description": "Filter by disabled status — true returns disabled clients, false returns enabled clients. Omit for no filter.",
"schema": {
"type": "boolean"
}
}
],
"security": [
{
"ManagementBearerAuth": []
Expand All @@ -38093,14 +38182,54 @@
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MCPClient"
"type": "object",
"description": "Paginated list of MCP clients.",
"required": [
"clients",
"count",
"total_count",
"limit",
"offset"
],
"properties": {
"clients": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MCPClient"
}
},
"count": {
"type": "integer",
"description": "Number of clients returned in this page"
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of clients matching the query (before pagination)"
},
"limit": {
"type": "integer",
"description": "Page size used for the response"
},
"offset": {
"type": "integer",
"description": "Page offset used for the response"
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BifrostError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
Expand Down Expand Up @@ -61466,10 +61595,6 @@
}
}
},
"is_deprecated": {
"type": "boolean",
"description": "True when the model is marked deprecated in the Bifrost pricing datasheet. Deprecated models remain listable for migration and compatibility workflows."
},
"pricing": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -71580,6 +71705,11 @@
"minimum": 1,
"default": 600,
"description": "Lifetime of the issued JWT Bearer token in seconds (default 600)."
},
"disable_vk_identity": {
"type": "boolean",
"default": false,
"description": "Require identity-provider login: virtual-key identity is removed from the consent flow, and existing virtual-key-mode grants are rejected at /mcp and denied on refresh. Only meaningful when mcp_server_auth_mode is 'oauth' and an identity provider is configured. Anonymous session identity is governed separately by enforce_auth_on_inference.\n"
}
},
"additionalProperties": false
Expand Down Expand Up @@ -71901,6 +72031,11 @@
"minimum": 1,
"default": 600,
"description": "Lifetime of the issued JWT Bearer token in seconds (default 600)."
},
"disable_vk_identity": {
"type": "boolean",
"default": false,
"description": "Require identity-provider login: virtual-key identity is removed from the consent flow, and existing virtual-key-mode grants are rejected at /mcp and denied on refresh. Only meaningful when mcp_server_auth_mode is 'oauth' and an identity provider is configured. Anonymous session identity is governed separately by enforce_auth_on_inference.\n"
}
},
"additionalProperties": false
Expand Down Expand Up @@ -78138,4 +78273,4 @@
}
Comment thread
greptile-apps[bot] marked this conversation as resolved.
}
}
}
}
78 changes: 74 additions & 4 deletions docs/openapi/paths/management/mcp.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,9 +76,79 @@ clients:
get:
operationId: getMCPClients
summary: List MCP clients
description: Returns a list of all configured MCP clients with their tools and connection state.
description: |
Returns a paginated list of configured MCP clients with their tools and connection state.
Supports case-insensitive name search and exact-match filtering by connection type, auth type,
code-mode, and enabled/disabled status. Multi-value filters accept a comma-separated list and
use OR semantics within a field.
tags:
- MCP
parameters:
- name: limit
in: query
description: Maximum number of clients to return (1–100, default 25).
schema:
type: integer
minimum: 1
maximum: 100
Comment thread
greptile-apps[bot] marked this conversation as resolved.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
default: 25
- name: offset
in: query
Comment thread
impoiler marked this conversation as resolved.
description: Number of clients to skip.
schema:
type: integer
minimum: 0
- name: search
in: query
description: Case-insensitive search by client name.
schema:
type: string
- name: server
in: query
description: Filter to a single client by its exact client_id.
schema:
type: string
- name: connection_type
in: query
description: Comma-separated connection types to include (OR semantics).
schema:
type: string
example: http,sse
- name: auth_type
in: query
description: Comma-separated auth types to include (OR semantics).
schema:
type: string
example: oauth,per_user_oauth
- name: state
in: query
description: |
Comma-separated runtime connection states to include (OR semantics),
resolved against live engine state. `connected` matches clients the engine
currently reports as connected; `disconnected` matches everything else.
schema:
type: string
example: connected
Comment thread
greptile-apps[bot] marked this conversation as resolved.
- name: all_virtual_keys
in: query
description: When true, include clients that are open to all virtual keys (allow_on_all_virtual_keys). ORs with virtual_keys.
schema:
type: boolean
- name: virtual_keys
in: query
description: Comma-separated virtual key IDs; includes clients explicitly assigned to any of them. ORs with all_virtual_keys.
schema:
type: string
- name: code_mode
in: query
description: Filter by code-mode clients. Omit for no filter.
schema:
type: boolean
- name: disabled
in: query
description: Filter by disabled status — true returns disabled clients, false returns enabled clients. Omit for no filter.
schema:
type: boolean
security:
- ManagementBearerAuth: []
responses:
Expand All @@ -87,9 +157,9 @@ clients:
content:
application/json:
schema:
type: array
items:
$ref: '../../schemas/management/mcp.yaml#/MCPClient'
$ref: '../../schemas/management/mcp.yaml#/MCPClientsListResponse'
'400':
$ref: '../../openapi.yaml#/components/responses/BadRequest'
'500':
$ref: '../../openapi.yaml#/components/responses/InternalError'

Expand Down
28 changes: 28 additions & 0 deletions docs/openapi/schemas/management/mcp.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -530,6 +530,34 @@ MCPClient:
$ref: '#/MCPVKConfigResponse'
description: Virtual key assignments for this MCP client

MCPClientsListResponse:
type: object
description: Paginated list of MCP clients.
required:
- clients
- count
- total_count
- limit
- offset
properties:
clients:
type: array
items:
$ref: '#/MCPClient'
count:
type: integer
description: Number of clients returned in this page
total_count:
type: integer
format: int64
description: Total number of clients matching the query (before pagination)
limit:
type: integer
description: Page size used for the response
offset:
type: integer
description: Page offset used for the response

ExecuteToolRequest:
oneOf:
- title: Chat (Default)
Expand Down
Loading