> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ezforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Servers

> Create and manage MCP servers

Servers represent deployed MCP instances. Each server gets a live subdomain at `{slug}.mcp.ezforge.ai`.

**Required scope:** `servers:read` (read), `servers:write` (mutations)

***

## List all servers

```
GET /v1/servers
```

Returns all servers across all of the authenticated user's projects (session auth), or all servers in the API key's project (API key auth with `servers:read` scope).

**Query parameters:** Standard pagination (`limit`, `cursor`) — supported for API key auth path.

**Response `200`:**

```json theme={null}
{
  "data": [
    {
      "id": "srv_xyz789",
      "name": "weather-server",
      "status": "running",
      "subdomain": "weather-server.mcp.ezforge.ai",
      "region": "ord",
      "authMode": "ezforge_managed",
      "cpu": "shared-1x",
      "memoryMb": 256,
      "autoStopSeconds": 300,
      "rollbackOnHealthCheckFailure": true,
      "deploymentRetentionCount": 10,
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-01-15T12:00:00Z"
    }
  ],
  "meta": { "cursor": null, "hasMore": false, "total": 1 }
}
```

***

## List servers in project

```
GET /v1/projects/:projectId/servers
```

**Query parameters:** Standard pagination (`limit`, `cursor`)

**Response `200`:**

```json theme={null}
{
  "data": [
    {
      "id": "srv_xyz789",
      "name": "weather-server",
      "status": "running",
      "subdomain": "weather-server.mcp.ezforge.ai",
      "region": "ord",
      "authMode": "ezforge_managed",
      "cpu": "shared-1x",
      "memoryMb": 256,
      "autoStopSeconds": 300,
      "rollbackOnHealthCheckFailure": true,
      "deploymentRetentionCount": 10,
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-01-15T12:00:00Z"
    }
  ],
  "meta": { "cursor": null, "hasMore": false, "total": 1 }
}
```

**Server statuses:**

| Status         | Description                        |
| -------------- | ---------------------------------- |
| `provisioning` | Being created for the first time   |
| `running`      | Active and serving requests        |
| `stopped`      | Stopped (idle auto-stop or manual) |
| `error`        | Failed deploy or health check      |
| `deleted`      | Permanently deleted                |

***

## Create server

```
POST /v1/projects/:projectId/servers
```

**Request body:**

```json theme={null}
{
  "name": "my-server",
  "slug": "my-server",
  "region": "ord",
  "cpu": "shared-1x",
  "memoryMb": 256,
  "autoStopSeconds": 300
}
```

**Fields:**

| Field             | Type    | Required | Default        | Description                                                                               |
| ----------------- | ------- | -------- | -------------- | ----------------------------------------------------------------------------------------- |
| `name`            | string  | ✓        | —              | Human-readable label (max 255 chars)                                                      |
| `slug`            | string  | —        | auto-generated | URL slug used as subdomain prefix; lowercase alphanumeric with hyphens (e.g. `my-server`) |
| `region`          | string  | —        | `ord`          | `ord`, `iad`, `lax`, `ams`, `syd`                                                         |
| `cpu`             | string  | —        | `shared-1x`    | `shared-1x`, `shared-2x`, `performance-1x`                                                |
| `memoryMb`        | integer | —        | `256`          | `256`, `512`, `1024`, `2048`                                                              |
| `autoStopSeconds` | integer | —        | `300`          | Idle seconds before auto-stop (60–86400)                                                  |

**Response `201`:** Created server object.

***

## Get server

```
GET /v1/servers/:serverId
```

**Response `200`:** Single server object.

***

## Update server

```
PATCH /v1/servers/:serverId
```

Update server configuration. All fields are optional; at least one must be provided.

**Request body fields:**

| Field                          | Type    | Description                                     |
| ------------------------------ | ------- | ----------------------------------------------- |
| `name`                         | string  | New display name (max 255 chars)                |
| `cpu`                          | string  | `shared-1x`, `shared-2x`, `performance-1x`      |
| `memoryMb`                     | integer | `256`, `512`, `1024`, `2048`                    |
| `autoStopSeconds`              | integer | 60–86400                                        |
| `rollbackOnHealthCheckFailure` | boolean | Auto-rollback if health check fails post-deploy |
| `deploymentRetentionCount`     | integer | Number of old deployments to keep (1–100)       |

**Response `200`:** Updated server object.

***

## Delete server

```
DELETE /v1/servers/:serverId
```

Stops the server and permanently deletes it along with all its deployments.

**Response `204`:** No content.

***

## Get server metrics

```
GET /v1/servers/:serverId/metrics
```

<Note>
  **Coming soon.** This endpoint is planned but not yet implemented. It currently returns `501 Not Implemented`.
</Note>

Returns aggregated usage statistics.

**Response `200`:**

```json theme={null}
{
  "data": {
    "requestCount": 12450,
    "errorCount": 3,
    "avgLatencyMs": 48,
    "p99LatencyMs": 210
  }
}
```