---
title: "corecluster_create"
url: https://docs.corefinity.com/mcp/tools/corecluster_create
type: tool
last_updated: 2026-11-13
feature: cluster-create
related:
  - https://docs.corefinity.com/api/reference/corecluster/create-cluster.md
  - https://docs.corefinity.com/guides/corecluster/create-a-cluster.md
---
# corecluster_create

**Create a CoreCluster.** Create a CoreCluster in a region on a package, optionally with up to ten first sites. It is charged as the package's price: price it first with corestack_billing_quote_preview. Scope: write. Long-running: answers with a task.

- Scope: `write`
- Runs as a task: yes

## When to use it

Create a CoreCluster in a region on a package, optionally with up to ten first sites. It is charged as the package's price: price it first with corestack_billing_quote_preview.

When another change in the same region is starting at that moment, the create waits for it instead of being refused: it is accepted at once, its operation stays `pending` with the `status_label` "Waiting for another change to finish. This carries on by itself." (the words the Control Panel shows), and it carries on by itself within a few minutes. Do not send it again. The task's status reads the same words while it waits.

When the region has no server of the cluster's kind yet, or none with room for it, the cluster waits while one is prepared or added, however long the region takes to make room: it carries on by itself, so there is nothing to retry; do not create it again. A first site whose disk the region has no room for yet waits the same way and carries on by itself. If that server's storage is not ready, the create fails with `failure_reason` `storage_unavailable` and the error "Storage in this region is not ready for a new cluster at the moment. Contact support." (corecluster_operation_get, the Control Panel and the REST API say the same). Do not retry: ask Corefinity support.

A CoreCluster that needs a new server in the region while changes to cluster capacity are paused for planned maintenance is not refused: it waits for its server and goes on by itself once the pause ends; there is nothing to retry.

When a step meets a temporary problem (the platform not answering yet, the cluster's SSH address not yet published), the create waits and tries that step again on its own instead of failing: corecluster_progress_get answers `retrying` with the stage, the attempt and the sentence "Setting up your cluster is taking longer than usual. We are trying again automatically." (or, at the SSH address, "Publishing your cluster's SSH address is taking longer than usual. We are trying again automatically."), and corecluster_operation_get carries the same sentence as the note `cluster_create_retrying`. Keep polling; do not create the cluster again. If a step fails on a temporary problem after the cluster was saved, the cluster is set up again on its own a few minutes later (up to twice), with the same name and its first sites carried over; `retrying` says so with "Setting up your cluster is taking longer than usual. We are setting it up again automatically." If a create fails before anything was saved, its name is free again at once, so the same company may create it again under the same name.

A create that was undone before anything was made gives its name back once its clean-up has finished, so the same name can be used again straight away by the same company; a name another company's cluster or a deleted cluster holds stays unavailable.

## Inputs

- `region` (string, up to 16 characters, required): uk, us, nl or aus — ready for the package (corestack_regions_list).
- `package` (string, up to 64 characters, required): A CoreCluster package key (corestack_packages_list).
- `name` (string, 1–100 characters, pattern `^[A-Za-z0-9][A-Za-z0-9 .&'()-]{0,99}$`, required): The cluster's name, unique in your company.
- `sites` (array of objects, up to 10 items): First sites: each row as corestack_in_corecluster_site_create takes it (corestack_site_provisioning_options lists the values).
  - `platform` (one of `wordpress`, `laravel`, `magento2`, `shopware`, required)
  - `domain` (string, 4–253 characters, required): The site's domain, without www.
  - `tier` (string, up to 16 characters, required): A tier the platform and the package offer.
  - `content` (one of `fresh`, `empty`, required): fresh: install the platform; empty: an empty site to migrate into.
  - `php_version` (string, up to 8 characters)
  - `mariadb_version` (string, up to 8 characters)
  - `fresh` (object): With content fresh: the first admin and the site's title.
    - `admin_email` (string, up to 255 characters)
    - `admin_username` (string, up to 32 characters)
    - `site_title` (string, up to 255 characters)
    - `locale` (string, up to 16 characters)
- `compute_family` (one of `general`, `optimised`): The server type: general (the default) or optimised.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "compute_family": {
      "description": "The server type: general (the default) or optimised.",
      "enum": [
        "general",
        "optimised"
      ],
      "type": "string"
    },
    "name": {
      "description": "The cluster's name, unique in your company.",
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9 .&'()-]{0,99}$",
      "type": "string"
    },
    "package": {
      "description": "A CoreCluster package key (corestack_packages_list).",
      "maxLength": 64,
      "type": "string"
    },
    "region": {
      "description": "uk, us, nl or aus — ready for the package (corestack_regions_list).",
      "maxLength": 16,
      "type": "string"
    },
    "sites": {
      "description": "First sites: each row as corestack_in_corecluster_site_create takes it (corestack_site_provisioning_options lists the values).",
      "items": {
        "additionalProperties": false,
        "properties": {
          "acknowledge": {
            "items": {
              "enum": [
                "eol"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "app_version": {
            "type": "string"
          },
          "content": {
            "description": "fresh: install the platform; empty: an empty site to migrate into.",
            "enum": [
              "fresh",
              "empty"
            ],
            "type": "string"
          },
          "domain": {
            "description": "The site's domain, without www.",
            "maxLength": 253,
            "minLength": 4,
            "type": "string"
          },
          "edition": {
            "enum": [
              "open_source"
            ],
            "type": "string"
          },
          "fresh": {
            "additionalProperties": false,
            "description": "With content fresh: the first admin and the site's title.",
            "properties": {
              "admin_email": {
                "maxLength": 255,
                "type": "string"
              },
              "admin_username": {
                "maxLength": 32,
                "type": "string"
              },
              "locale": {
                "maxLength": 16,
                "type": "string"
              },
              "site_title": {
                "maxLength": 255,
                "type": "string"
              }
            },
            "type": "object"
          },
          "mariadb_version": {
            "maxLength": 8,
            "type": "string"
          },
          "node_acknowledge": {
            "description": "[\"eol\"] once the person knows the chosen Node.js major is end of life (refused with ack_required otherwise).",
            "items": {
              "enum": [
                "eol"
              ],
              "type": "string"
            },
            "maxItems": 1,
            "type": "array"
          },
          "node_major": {
            "description": "The Node.js major (corestack_site_provisioning_options lists each platform's, with its status). Left out, the default for new sites.",
            "maximum": 99,
            "minimum": 10,
            "type": "integer"
          },
          "php_version": {
            "maxLength": 8,
            "type": "string"
          },
          "platform": {
            "enum": [
              "wordpress",
              "laravel",
              "magento2",
              "shopware5"
            ],
            "type": "string"
          },
          "search": {
            "description": "Search (OpenSearch) on or off, on a platform that offers it.",
            "type": "boolean"
          },
          "tier": {
            "description": "A tier the platform and the package offer.",
            "maxLength": 16,
            "type": "string"
          },
          "varnish": {
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "version": {
                "type": "string"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "platform",
          "domain",
          "tier",
          "content"
        ],
        "type": "object"
      },
      "maxItems": 10,
      "type": "array"
    }
  },
  "required": [
    "region",
    "package",
    "name"
  ],
  "type": "object"
}
```

## Refusals

- `invalid_arguments` naming `name` with "this cluster name is not available": the name is taken, or the SSH address it would give the cluster (`ssh-<company>-<name>.cfstack.io`) is already another site's; nothing was created — choose another name.
- `compute_blocked`: the region's servers cannot take a new CoreCluster at the moment (every CoreCluster runs on the region's shared compute servers); nothing was created — try later, or contact support.
- `ack_required`: the change needs the person's acknowledgements first; `required[]` lists them — confirm with the person, then call again with them.
- `feature_off`: an input needs a feature that is switched off (for example `apply: "tonight"` while the maintenance window queue is switched off); leave that input out.
- `demo_keep_required`: the company is on a free demo that is not kept yet, and a new standalone cluster costs money: ask the person to keep the demo first (`corestack_demo_keep`, or open `keep_url`); `change` names it and its monthly price.
- `rate_limited`: the company has created as many CoreClusters this hour as its limit allows (10 by default, for everyone of the company together, shared with the Control Panel and the API). A create that is refused does not count. `retry_after_seconds` says when the next one is allowed: wait that long, then call again.
- `invalid_arguments` on a row's `content` ("PHP sites start empty: deploy your code"), or on its `app_version`, `edition` or `acknowledge` ("The <field> field is not part of this request.", naming it): PHP has no installer and no versions to choose; create it with `content: empty` and leave those inputs out.
- `invalid_arguments` on a first site's `sites.<i>.platform` or `sites.<i>.tier` ("<package> does not offer <platform> sites on this cluster", or "<package> does not offer <size> on this cluster"; where a larger package offers it the sentence adds "Upgrade to <that package> or larger to add one."): the package does not offer that site. Choose another platform or size, or a package that offers it — nothing was created.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corecluster_create",
  "arguments": {
    "region": "uk",
    "package": "cs4",
    "name": "Staging"
  }
}
```

## What it installs

Each `sites[]` row is a create of its own (corestack_in_corecluster_site_create's "What it installs"): a default version not yet open to new sites never refuses it, the row installs the newest one that is, and corestack_site_get names the choice in `site.create_fallbacks`, with `now_available` on a PHP entry once that version opens to new sites.

A platform with no installer of its own (PHP, while it is offered) starts empty: send `content: empty` and no `fresh`, `app_version`, `edition` or `acknowledge`; the site takes the platform's default PHP and MariaDB versions unless you name them. The person then deploys their own code to it, as to any empty site.

## Prompt

```text
Using the Corefinity MCP server, call corecluster_create with region uk, package cs4, name Staging. (Create a CoreCluster.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [POST /api/corestack/clusters](https://docs.corefinity.com/api/reference/corecluster/create-cluster.md)
- Guide: [Create a cluster](https://docs.corefinity.com/guides/corecluster/create-a-cluster.md)
