# List all instances for an MCP server

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

Retrieves a paginated list of user instances (user IDs) associated with a specific Model Control Protocol (MCP) server. This endpoint supports pagination to handle servers with many instances.

---

## GET `/api/v3/mcp/servers/{serverId}/instances`

**Endpoint:** `https://backend.composio.dev/api/v3/mcp/servers/{serverId}/instances`

**Summary:** List all instances for an MCP server

Retrieves a paginated list of user instances (user IDs) associated with a specific Model Control Protocol (MCP) server. This endpoint supports pagination to handle servers with many instances.

### Authentication

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

### Path Parameters

- `serverId` (string) *(required)*: The ID of the MCP server

### Query Parameters

- `page_no` (number,null): Page number for pagination (1-based)
- `limit` (number,null): Number of items per page (default: 20)
- `search` (string): Search instances by user ID/instance ID
- `order_by` (enum: "created_at" | "updated_at"): Field to order results by
- `order_direction` (enum: "asc" | "desc"): Direction of ordering

### Responses

#### 200 - Successfully retrieved MCP server instances. Returns the list of user IDs associated with this server.

**Response Schema:**

- `instances` (array<object>) *(required)*: List of instance objects associated with this MCP server for the current page
  - Array items:
    - `id` (string) *(required)*: UUID of the instance record
    - `instance_id` (string) *(required)*: The instance identifier (same as the user_id)
    - `mcp_server_id` (string) *(required)*: UUID of the parent MCP server
    - `created_at` (string) *(required)*: Date and time when this instance was created
    - `updated_at` (string) *(required)*: Date and time when this instance was last modified
- `server_id` (string) *(required)*: UUID of the MCP server
- `server_name` (string) *(required)*: Name of the MCP server
- `total_pages` (number) *(required)*: Total number of pages in the paginated response
- `current_page` (number) *(required)*: Current page number being returned

**Example Response:**

```json
{
  "instances": [
    {
      "id": "string",
      "instance_id": "string",
      "mcp_server_id": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "server_id": "string",
  "server_name": "string",
  "total_pages": 1,
  "current_page": 1
}
```

#### 400 - Bad request. The server ID parameter may be 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>)

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

#### 404 - MCP server not found. No server with the specified ID exists.

**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/string/instances" \
  -H "x-api-key: YOUR_API_KEY"
```