> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# 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.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `filter.id` | string | No | Filter by MCP configuration id. |
| `filter.mcp_server_url` | string | No | 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.name` | string | No | Case-insensitive exact match on configuration name. Allowed characters: letters (a–z, A–Z), digits (0–9), hyphens (-), and underscores (_). Maximum 100 characters. |
| `filter.provider` | string | No | Return only servers with a connection for this app, such as `GMAIL`. |
| `page_size` | integer | No | Number of configs to return per page (max 30). |
| `page_token` | string | No | Pagination token to fetch the next or previous page. |
| `search` | string | No | Return servers whose name contains this text, case-insensitive. At least 3 characters. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `configs` | array of object | List of MCP configurations. |
| `configs.connection_tool_mappings` | array of object | List of connection-to-tool mappings for this MCP config. Maximum 25 entries. |
| `configs.connection_tool_mappings.connected_account_id` | string | Connected account backing this connection in the MCP instance context. |
| `configs.connection_tool_mappings.connected_account_status` | string | Authentication status for the connected account. |
| `configs.connection_tool_mappings.connection_id` | string | Unique ID of the connection. |
| `configs.connection_tool_mappings.connection_name` | string | Developer-assigned connection name. |
| `configs.connection_tool_mappings.provider` | string | Provider name for this connection. |
| `configs.connection_tool_mappings.tools` | array of string | List of tool names linked to this connection (empty = all tools). |
| `configs.description` | string | Description of the MCP configuration. |
| `configs.id` | string | Unique ID of the MCP config. |
| `configs.mcp_server_url` | string | The URL MCP clients connect to for this server. Every user and session shares it; the session token identifies the user. |
| `configs.name` | string | Unique name for the MCP configuration. Must be 1–100 characters. Allowed characters: lowercase letters (a–z), digits (0–9), hyphens (-), and underscores (_). |
| `next_page_token` | string | Pagination token to fetch the next page. |
| `prev_page_token` | string | Pagination token to fetch the previous page. |
| `total_size` | integer | Total number of configs matching the filter. |

**Errors**

- `400`: Invalid request - bad filter or pagination parameters
- `401`: Authentication required

**Request**

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

**Response**

```json
{
  "configs": [
    {
      "id": "cfg_85630864460904897",
      "name": "repo-assistant",
      "description": "Reads the user's GitHub repositories and issues",
      "connection_tool_mappings": [
        {
          "connection_id": "conn_70219645518267719",
          "connection_name": "github-connect",
          "provider": "GITHUB",
          "tools": [
            "github_user_repos_list",
            "github_issues_list"
          ]
        }
      ],
      "mcp_server_url": "https://your-env.scalekit.dev/mcp/v3/servers/3d9f6a2e-7b41-4c8e-a5d2-0f1e8b6c4a93"
    }
  ],
  "next_page_token": "",
  "prev_page_token": "",
  "total_size": 1
}
```

**Python SDK:** `scalekit_client.actions.mcp.list_configs`

List MCP configurations with optional pagination and filtering.

```python
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
```

Example:

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

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `page_size` | `Optional[int]` | No | Maximum number of configs to include in the current page. Defaults to the server-side default (typically 20). |
| `page_token` | `Optional[str]` | No | Cursor token returned by a previous `list_configs` call. Pass this to fetch the next page of results. |
| `filter_id` | `Optional[str]` | No | Return only the server with this ID, such as `"cfg_85630864460904897"`. |
| `filter_provider` | `Optional[str]` | No | Return only servers with a connection for this app, such as `"GMAIL"`. |
| `filter_name` | `Optional[str]` | No | Return only the server with this name, case-insensitive exact match, such as `"repo-assistant"`. |
| `filter_mcp_server_url` | `Optional[str]` | No | Return only the server with this MCP server URL, such as `"https://your-env.scalekit.dev/mcp/v3/servers/3d9f6a2e-7b41-4c8e-a5d2-0f1e8b6c4a93"`. |
| `search` | `Optional[str]` | No | 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`.

**Node.js SDK:** `scalekit.actions.mcp.listConfigs`

Lists MCP configurations for the current environment.

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

Example:

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

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | `string` | No | Return servers whose name contains this text, case-insensitive. At least 3 characters. |
| `pageSize` | `number` | No | Maximum number of configurations to return per page (max 30; a larger value fails with `[invalid_argument] Validation error`). |
| `pageToken` | `string` | No | Token from a previous `listConfigs` response. |

Returns `Promise<ListMcpConfigsResponse>`.

**Used in**

- [Build a multi-agent email triage crew with CrewAI](https://docs.scalekit.com/cookbooks/crewai-agentkit-email-triage/)
- [Claude Managed Agents](https://docs.scalekit.com/agentkit/examples/claude-managed-agents/)
- [Create a Virtual MCP server](https://docs.scalekit.com/agentkit/mcp/configure-mcp-server/)
- [CrewAI](https://docs.scalekit.com/agentkit/examples/crewai/)
- [Mastra](https://docs.scalekit.com/agentkit/examples/mastra/)


Part of [Virtual MCP servers](https://docs.scalekit.com/agentkit/reference/virtual-mcp-servers/) in the [AgentKit API reference](https://docs.scalekit.com/agentkit/reference/). Authentication: https://docs.scalekit.com/agentkit/reference/authentication.md. Errors and rate limits: https://docs.scalekit.com/agentkit/reference/errors.md. Pagination: https://docs.scalekit.com/agentkit/reference/pagination.md


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |