# Create a new custom MCP server with multiple apps

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

Creates a new Model Control Protocol (MCP) server instance that can integrate with multiple applications or toolkits simultaneously. This endpoint allows you to create a server that can access tools from different applications, making it suitable for complex workflows that span multiple services.

---

## POST `/api/v3/mcp/servers/custom`

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

**Summary:** Create a new custom MCP server with multiple apps

Creates a new Model Control Protocol (MCP) server instance that can integrate with multiple applications or toolkits simultaneously. This endpoint allows you to create a server that can access tools from different applications, making it suitable for complex workflows that span multiple services.

### Authentication

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

### Request Body

**Schema:**

- `name` (string) *(required)*: Human-readable name to identify this custom MCP server (4-30 characters, alphanumeric, spaces, and hyphens only)
- `auth_config_ids` (array<string>): ID references to existing authentication configurations
- `toolkits` (array<string>): List of application/toolkit identifiers to enable for this server
- `allowed_tools` (array<string>): Tool identifiers to enable that aren't part of standard toolkits
- `custom_tools` (array<string>): DEPRECATED: Use allowed_tools instead. Tool identifiers to enable that aren't part of standard toolkits
- `managed_auth_via_composio` (boolean): Whether to manage authentication via Composio

**Example:**

```json
{
  "name": "string",
  "auth_config_ids": [
    "string"
  ],
  "toolkits": [
    "string"
  ],
  "allowed_tools": [
    "string"
  ],
  "custom_tools": [
    "string"
  ],
  "managed_auth_via_composio": true
}
```

### Responses

#### 201 - Custom MCP server created successfully. Returns the complete server configuration including connection details and command instructions for all specified applications.

**Response Schema:**

- `id` (string) *(required)*: Unique identifier for the newly created custom MCP server
- `name` (string) *(required)*: Human-readable name of the custom MCP server
- `auth_config_ids` (array<string>) *(required)*: ID references to the auth configurations used by this server
- `allowed_tools` (array<string>) *(required)*: List of tool identifiers that are enabled for this server
- `mcp_url` (string) *(required)*: URL endpoint for establishing connection to this MCP server
- `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

**Example Response:**

```json
{
  "id": "string",
  "name": "string",
  "auth_config_ids": [
    "string"
  ],
  "allowed_tools": [
    "string"
  ],
  "mcp_url": "string",
  "commands": {
    "cursor": "string",
    "claude": "string",
    "windsurf": "string"
  }
}
```

#### 400 - Bad request. The request body may be invalid, missing required parameters, or contain invalid toolkit identifiers.

**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 create 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 POST "https://backend.composio.dev/api/v3/mcp/servers/custom" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "auth_config_ids": [
      "string"
    ],
    "toolkits": [
      "string"
    ],
    "allowed_tools": [
      "string"
    ],
    "custom_tools": [
      "string"
    ],
    "managed_auth_via_composio": true
  }'
```