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:

{
  "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,
      "runMode": "auto_suspend",
      "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:

{
  "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,
      "runMode": "auto_suspend",
      "rollbackOnHealthCheckFailure": true,
      "deploymentRetentionCount": 10,
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-01-15T12:00:00Z"
    }
  ],
  "meta": { "cursor": null, "hasMore": false, "total": 1 }
}

Every server object includes a runMode field (see Run modes). 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:

{
  "name": "my-server",
  "slug": "my-server",
  "region": "ord",
  "cpu": "shared-1x",
  "memoryMb": 256,
  "autoStopSeconds": 300,
  "runMode": "auto_suspend"
}

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`	Deprecated. Has no effect: idle stop/suspend timing is controlled by `runMode` (see Run modes). Still accepted (60–86400) and stored, so existing clients keep working. Will be removed in a future release
`runMode`	string	—	`auto_suspend`	`auto_stop`, `auto_suspend`, `always_on` (see Run modes)

The Free plan is limited to cpu shared-1x and memoryMb 256. Requesting a larger size returns 403 (plan_limit_exceeded); paid plans can use every listed size. runMode selects the idle behavior; always_on returns 403 (plan_limit_exceeded) on the Free plan, 403 (spend_cap_exceeded) when the projected period total would pass the spend cap, and an invalid value returns 422. See Run modes and Always-on and the spend cap. Response 201: Created server object.

Get server

GET /v1/servers/:serverId

Response 200: Single server object, plus a machineState field reporting the live state of the underlying machine.

{
  "data": {
    "id": "srv_xyz789",
    "name": "weather-server",
    "status": "running",
    "machineState": "stopped",
    "subdomain": "weather-server.mcp.ezforge.ai"
  }
}

(Other server fields omitted for brevity.) machineState values:

Value	Description
`running`	The machine is running right now
`stopped`	The machine is stopped or suspended but healthy (for example, idle auto-stop or auto-suspend)
`unknown`	The live state could not be determined — no machine yet, the lifecycle service is unavailable, the lookup failed or took longer than 3 seconds, or the machine is in an error or transitional state

status is the server’s recorded lifecycle status and is not updated when the machine idle-stops or auto-starts, so it can differ from machineState. Use machineState to check whether the machine is running at the moment of the request. The lookup is best-effort: a failure never fails the request and never changes status.

Run modes

Each server has a runMode that controls what its machine does when idle. It is returned on every server object.

Value	Idle behavior
`auto_stop`	The machine stops when idle and restarts on the next request
`auto_suspend`	The machine is suspended when idle and resumes on the next request
`always_on`	One machine stays running; it is never stopped for idleness

Always-on and the spend cap

Creating a server with always_on, switching a server to it, or changing the size of a server that is already always_on is refused with 403 (spend_cap_exceeded) when the projected total for the billing period would exceed the account’s spend cap. The projection is the plan fee, plus metered usage so far this period (before credit), plus the always-on hours for the rest of the period at the per-hour price for the machine size (the monthly price ÷ 730), plus the remaining always-on charge of the account’s other always-on servers. The error message names the projected total, the cap, and the billing page where the cap can be raised. If billing cannot be read, the request returns 503 (billing_unavailable) and changes nothing. Scale accounts, whose cap is set by contract, skip this check. New servers are created with auto_suspend. Servers that existed before run modes were introduced keep auto_stop, the behavior their machines already had. A suspended machine reports machineState: "stopped" (see Get server). The platform keeps a timestamped history of each server’s runMode for usage metering. A row is recorded when the server is created and on each runMode change made with PATCH /v1/servers/:serverId. A change is recorded only after the machine update succeeds, so a failed update records nothing and a retry with the same value is still recorded. This history has no public endpoint and adds no request or response fields.

Compute metering

Compute usage is recorded in the platform’s usage ledger once per closed UTC hour for each server, keyed by the machine’s size (for example shared-1x-256mb). Which meter an hour uses depends on the server’s runMode during that hour:

Hour	Recorded usage
`runMode` was `always_on` at any point in the hour	`always_on_hours` = 1 for the whole hour, even if the server switched to or from `always_on` mid-hour, provided the machine’s size was sampled. No `awake_seconds` is recorded for that hour.
Any other hour	`awake_seconds` = the seconds the Fly machine was in the `started` state.

The platform polls each machine’s state every 5 minutes and collects closed hours every 15 minutes, re-checking the last 24 hours on each pass. Re-running an hour replaces its quantity, so usage is never double-counted. If the samples do not establish what the machine did in an hour (for example, polls are missing for more than 15 minutes, a state change cannot be placed in time, or no sample reports the machine’s size), no usage is recorded for that hour. It is not estimated, and a later pass retries it for up to 24 hours, while the samples exist. Machines whose CPU and memory are not one of the billed sizes are not metered. Polling and collecting are separate loops, each under its own lock, so only one platform instance polls at a time and only one collects at a time. A long collection pass never delays polling, so it cannot leave gaps in the machine-state samples. If an instance cannot take a loop’s lock, it skips that pass. The collector reads and writes 100 servers at a time. Re-running an hour that already holds the computed quantity writes nothing. If recording a batch fails, its hours are not recorded that pass, and the next pass retries them while they are inside the 24-hour window. Hours of a server deleted while the pass is running are not recorded. Compute metering is internal. It adds no endpoint and no request or response fields.

runMode can be set on POST /v1/projects/:projectId/servers and PATCH /v1/servers/:serverId. The Free plan is limited to auto_stop and auto_suspend; requesting always_on returns 403 (plan_limit_exceeded). Paid plans may use all three. An invalid value returns 422.

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	Deprecated. 60–86400. Has no effect: idle stop/suspend timing is controlled by `runMode`. Will be removed in a future release (see Create server)
`runMode`	string	`auto_stop`, `auto_suspend`, `always_on` (see Run modes)
`rollbackOnHealthCheckFailure`	boolean	Auto-rollback if health check fails post-deploy
`deploymentRetentionCount`	integer	Number of old deployments to keep (1–100)

The same plan limits apply as on create: a Free account setting cpu or memoryMb above shared-1x / 256, or runMode to always_on, receives 403 (plan_limit_exceeded). An invalid runMode returns 422. A switch to always_on, or a cpu / memoryMb change on a server that is already always_on, returns 403 (spend_cap_exceeded) when the projected period total would pass the spend cap (see Always-on and the spend cap). 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

Coming soon. This endpoint is planned but not yet implemented. It currently returns 501 Not Implemented.

Returns aggregated usage statistics. Response 200:

{
  "data": {
    "requestCount": 12450,
    "errorCount": 3,
    "avgLatencyMs": 48,
    "p99LatencyMs": 210
  }
}

API Reference

Ready

List all servers

List servers in project

Create server

Get server

Run modes

Always-on and the spend cap

Compute metering

Update server

Delete server

Get server metrics

​List all servers

​List servers in project

​Create server

​Get server

​Run modes

​Always-on and the spend cap

​Compute metering

​Update server

​Delete server

​Get server metrics

List all servers

List servers in project

Create server

Get server

Run modes

Always-on and the spend cap

Compute metering

Update server

Delete server

Get server metrics