List Virtual MCP servers

GET/api/v1/mcp/configs

Lists the Virtual MCP servers in your environment. Filter by ID, exact name, provider or MCP server URL, or pass search to match part of the name.

This page as markdown Virtual MCP servers overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Query parameters

filter.idstring

Filter by MCP configuration id

filter.mcp_server_urlstring

Filter configs by MCP server URL. The UUID is extracted from the last path segment of the URL and used to find the matching configuration.

filter.namestring

Case-insensitive exact match on configuration name. Allowed characters: letters (a–z, A–Z), digits (0–9), hyphens (-), and underscores (_). Maximum 100 characters.

filter.providerstring

Return only servers with a connection for this app, such as GMAIL.

page_sizeinteger

Number of configs to return per page (max 30)

page_tokenstring

Pagination token to fetch the next or previous page

searchstring

Return servers whose name contains this text, case-insensitive. At least 3 characters.

scalekit_client.actions.mcp.list_configs

List MCP configurations with optional pagination and filtering.

scalekit_client.actions.mcp.list_configs(
    page_size: Optional[int] = None,
    page_token: Optional[str] = None,
    filter_id: Optional[str] = None,
    filter_provider: Optional[str] = None,
    filter_name: Optional[str] = None,
    filter_mcp_server_url: Optional[str] = None,
    search: Optional[str] = None,
) -> ListMcpConfigsResponse

Parameters

page_sizeOptional[int]

Maximum number of configs to include in the current page. Defaults to the server-side default (typically 20).

page_tokenOptional[str]

Cursor token returned by a previous list_configs call. Pass this to fetch the next page of results.

filter_idOptional[str]

Return only the server with this ID, such as "cfg_85630864460904897".

filter_providerOptional[str]

Return only servers with a connection for this app, such as "GMAIL".

filter_nameOptional[str]

Return only the server with this name, case-insensitive exact match, such as "repo-assistant".

filter_mcp_server_urlOptional[str]

Return only the server with this MCP server URL, such as "https://your-env.scalekit.dev/mcp/v3/servers/3d9f6a2e-7b41-4c8e-a5d2-0f1e8b6c4a93".

searchOptional[str]

Return servers whose name contains this text, case-insensitive. At least 3 characters.

Returns ListMcpConfigsResponse: The page of servers in configs, with next_page_token and total_size.

From scalekit-sdk-python 2.22.0.

scalekit.actions.mcp.listConfigs

Lists MCP configurations for the current environment.

scalekit.actions.mcp.listConfigs(
  options?: {
    search?: string;
    pageSize?: number;
    pageToken?: string;
  },
): Promise<ListMcpConfigsResponse>

Parameters

searchstring

Return servers whose name contains this text, case-insensitive. At least 3 characters.

pageSizenumber

Maximum number of configurations to return per page (max 30; a larger value fails with [invalid_argument] Validation error).

pageTokenstring

Token from a previous listConfigs response.

Returns Promise<ListMcpConfigsResponse>.

From @scalekit-sdk/node 2.21.0.

Response 200

configsarray of object

List of MCP configurations

Show 6 child attributes

connection_tool_mappingsarray of object

List of connection-to-tool mappings for this MCP config. Maximum 25 connections in DIRECT mode.

Show 6 child attributes

connected_account_idstring

Connected account backing this connection in the MCP instance context

connected_account_statusstring

Authentication status for the connected account

connection_idstring

Unique ID of the connection

connection_namestring

Developer-assigned connection name

providerstring

Provider name for this connection

toolsarray of string

List of tool names linked to this connection (empty = all tools)

descriptionstring

Description of the MCP configuration

idstring

Unique ID of the MCP config

mcp_server_urlstring

The URL MCP clients connect to for this server. Every user and session shares it; the session token identifies the user.

namestring

Unique name for the MCP configuration. Must be 1–100 characters. Allowed characters: lowercase letters (a–z), digits (0–9), hyphens (-), and underscores (_).

tool_exposurestring (enum)

How the server exposes tools to agents. DIRECT lists every tool you map to it, for up to 25 connections. META gives agents five tools to search for, inspect and run the mapped tools, with no limit on connections. DIRECT is the default when you create a server without it.

DIRECTMETA

next_page_tokenstring

Pagination token to fetch the next page

prev_page_tokenstring

Pagination token to fetch the previous page

total_sizeinteger

Total number of configs matching the filter

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - bad filter or pagination parameters

401Authentication required

Used in

Request

curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/configs" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "search=repo-assistant"

result = scalekit_client.actions.mcp.list_configs(
    search="repo-assistant",
)

const result = await scalekit.actions.mcp.listConfigs({
  search: "repo-assistant",
});

Response 200

1
{
2
  "configs": [
3
    {
4
      "id": "cfg_85630864460904897",
5
      "name": "repo-assistant",
6
      "description": "Reads the user's GitHub repositories and issues",
7
      "connection_tool_mappings": [
8
        {
9
          "connection_id": "conn_70219645518267719",
10
          "connection_name": "github-connect",
11
          "provider": "GITHUB",
12
          "tools": [
13
            "github_user_repos_list",
14
            "github_issues_list"
15
          ]
16
        }
17
      ],
18
      "mcp_server_url": "https://your-env.scalekit.dev/mcp/v3/servers/3d9f6a2e-7b41-4c8e-a5d2-0f1e8b6c4a93",
19
      "tool_exposure": "DIRECT"
20
    }
21
  ],
22
  "next_page_token": "",
23
  "prev_page_token": "",
24
  "total_size": 1
25
}