# Create a new MCP server instance

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

Creates a new instance for a Model Control Protocol (MCP) server. This endpoint validates that the user has connected accounts for all auth configurations associated with the MCP server before creating the instance.

---

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

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

**Summary:** Create a new MCP server instance

Creates a new instance for a Model Control Protocol (MCP) server. This endpoint validates that the user has connected accounts for all auth configurations associated with the MCP server before creating the instance.

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

### Request Body

**Schema:**

- `user_id` (string) *(required)*: The user ID (entity ID) that will be used as both the user identifier and instance ID

**Example:**

```json
{
  "user_id": "string"
}
```

### Responses

#### 201 - Successfully created MCP server instance. Returns the created instance details.

**Response Schema:**

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

**Example Response:**

```json
{
  "id": "string",
  "instance_id": "string",
  "mcp_server_id": "string",
  "created_at": "string",
  "updated_at": "string"
}
```

#### 400 - Bad request. The request parameters may be invalid or the instance ID already 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>)

#### 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 user does not have connected accounts for all required auth configurations.

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

#### 409 - Conflict. An instance with this ID already exists for the server.

**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 POST "https://backend.composio.dev/api/v3/mcp/servers/string/instances" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "string"
  }'
```