# List MCP servers with optional filters and pagination

**Documentation:** /reference/api-reference/mcp/getMcpServers

Retrieves a paginated list of MCP servers associated with the authenticated project. Results can be filtered by name, toolkit, or authentication configuration ID. MCP servers are used to provide Model Control Protocol integration points for connecting AI assistants to your applications and services.

---

## GET `/api/v3/mcp/servers`

**Endpoint:** `https://backend.composio.dev/api/v3/mcp/servers`

**Summary:** List MCP servers with optional filters and pagination

Retrieves a paginated list of MCP servers associated with the authenticated project. Results can be filtered by name, toolkit, or authentication configuration ID. MCP servers are used to provide Model Control Protocol integration points for connecting AI assistants to your applications and services.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Query Parameters

- `name` (string): Filter MCP servers by name (case-insensitive partial match)
- `toolkits` (string): Comma-separated list of toolkit slugs to filter servers by
- `auth_config_ids` (string): Comma-separated list of auth config IDs to filter servers by
- `order_by` (enum: "created_at" | "updated_at"): Field to order results by
- `order_direction` (enum: "asc" | "desc"): Direction of ordering
- `page_no` (number,null): Page number for pagination (1-based)
- `limit` (number,null): Number of items per page (default: 10)

### Responses

#### 200 - Successfully retrieved MCP servers. Returns a paginated list of server configurations including connection details and command instructions.

**Response Schema:**

- `items` (array<object>) *(required)*: Array of MCP server configurations
  - Array items:
    - `id` (string) *(required)*: UUID of the MCP server instance
    - `name` (string) *(required)*: User-defined descriptive name for this MCP server
    - `auth_config_ids` (array<string>) *(required)*: ID references to the auth configurations used by this server
    - `allowed_tools` (array<string>) *(required)*: Array of tool slugs that this MCP server is allowed to use
    - `mcp_url` (string) *(required)*: [DEPRECATED] Please use the URL with user_id or connected_account_id query param
    - `toolkits` (array<string>) *(required)*: Array of toolkit slugs that this MCP server is allowed to use
    - `toolkit_icons` (object) *(required)*: Object mapping each toolkit slug to its icon/logo URL for display purposes
      - `[key: string]` (string)
    - `commands` (object) *(required)*: Set of command line instructions for connecting various clients to this MCP server
      - `cursor` (string) *(required)*: Command line instruction for Cursor client setup
      - `claude` (string) *(required)*: Command line instruction for Claude client setup
      - `windsurf` (string) *(required)*: Command line instruction for Windsurf client setup
    - `updated_at` (string) *(required)*: Date and time when this server configuration was last modified
    - `created_at` (string) *(required)*: Date and time when this server was initially created
    - `server_instance_count` (number) *(required)*: Total count of active user instances connected to this server
    - `managed_auth_via_composio` (boolean) *(required)*: Whether the MCP server is managed by Composio
- `total_pages` (number) *(required)*: Total number of pages in the paginated response
- `current_page` (number) *(required)*: Current page number being returned

**Example Response:**

```json
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "auth_config_ids": [
        "..."
      ],
      "allowed_tools": [
        "..."
      ],
      "mcp_url": "string",
      "toolkits": [
        "..."
      ],
      "toolkit_icons": {
        "key": "..."
      },
      "commands": {
        "cursor": "...",
        "claude": "...",
        "windsurf": "..."
      },
      "updated_at": "string",
      "created_at": "string",
      "server_instance_count": 1,
      "managed_auth_via_composio": true
    }
  ],
  "total_pages": 1,
  "current_page": 1
}
```

#### 400 - Bad request. The query parameters may be invalid or in an incorrect format.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized. Authentication is required or the provided credentials are invalid.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 403 - Forbidden. The authenticated user does not have permission to view MCP servers for this project.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error. An unexpected error occurred while processing the request.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X GET "https://backend.composio.dev/api/v3/mcp/servers" \
  -H "x-api-key: YOUR_API_KEY"
```