---
title: "corestack_site_attach_domain"
url: https://docs.corefinity.com/mcp/tools/corestack_site_attach_domain
type: tool
last_updated: 2026-11-13
feature: domains
related:
  - https://docs.corefinity.com/api/reference/domains/attach-site-domain.md
  - https://docs.corefinity.com/guides/sites/go-live/add-a-domain.md
---
# corestack_site_attach_domain

**Attach a domain.** Attach hosts to a site or environment and make it serve them: claims the hosts, issues the certificate, switches the row to its live address and rewrites its database from the preview host to the canonical one. Scope: write. Long-running: answers with a task.

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

## When to use it

Attach hosts to a site or environment and make it serve them: claims the hosts, issues the certificate, switches the row to its live address and rewrites its database from the preview host to the canonical one.

Behind Cloudflare: when corestack_site_attach_domain_check lists a host in `proxied_unconfirmed`, Cloudflare proxies it in a zone the Control Panel cannot look behind, so the check cannot see the address behind the proxy. Each such host needs proof that the person controls it: a TXT record named `verification.name` holding `verification.value` (the value is their company's), added in Cloudflare. Ask the person to add it if `verification.found` is false, to check in Cloudflare that the host's record points at the address the check names (`expected_ip`), and send `proxied_records_checked: true` only once they have done both. The attach reads the TXT record again itself. Without the flag the attach answers `invalid_arguments` on `proxied_records_checked` and nothing is changed. A host whose `confirmable` is false is refused on `hosts` whatever you send: with its `challenge_path.note` when the certificate path blocks it (the change to make in Cloudflare, for example setting SSL/TLS to Full), otherwise with the TXT record to add (or why it could not be read). Make that change, check again, then attach. The operation's notes then say the record was confirmed rather than checked.

On a staging or development environment the attach never switches outgoing mail on: a Magento 2 copy's mail hold (`system/smtp/disable`) stays as it is, and the operation records it as held for the row's role. Only a production row's attach releases mail (on a `pending_dns` attach, at the cutover). The last step flushes the row's Redis; a row with no Redis records the flush as skipped and the attach still completes.

After the store change completes and before changing DNS:

Request `/` with `corestack_site_smoke_test`, setting `host` to the store domain. The final URL must be on that
store's `base_url` host from `corestack_site_magento_stores_list` (the domain itself, or its bare or `www` form
when the base URL uses it), and the title must be that store's. Magento redirects to the store's base URL; a
redirect to any other host means its base URL points elsewhere.
GraphQL picks its store from the `Store` header, so it cannot prove a domain's store.

## Inputs

- `site_id` (integer, ≥ 1, required)
- `hosts` (array of string, 1–253 characters, 1–10 items, required): The hosts to attach (production row: the site's domain or its www form among them; any other row: never it). A host-migration copy made under its provider's platform host may leave that name out (it can never point here).
- `canonical` (string, 1–253 characters, required): The host the row is served on; one of hosts.
- `www` (one of `www`, `bare`): Which form the other redirects to; default from canonical.
- `confirm_domain` (string, up to 253 characters, required): The site's domain on the production row; the canonical host on any other row.
- `point_dns` (boolean): Write the DNS plan through your company's Cloudflare connection.
- `confirm_replacements` (boolean): Allow the DNS plan to replace existing records.
- `pending_dns` (boolean): Attach before DNS points at the platform (a migration's test of the copy): crons and outgoing mail stay held until the cutover. Each host that does not point here yet needs its TXT proof of control; a refusal names the record and its value. Not with point_dns.
- `proxied_records_checked` (boolean): The person has checked in Cloudflare that every host corestack_site_attach_domain_check lists in proxied_unconfirmed points at the platform's address. Ask them; never set it for them.
- `aliases` (array of objects, 1 to 9): How non-canonical hosts are served on Shopware and Magento 2.
  - `host` (string, 1 to 253 characters, required): One of hosts, other than canonical, listed once.
  - `serve` (one of `redirect`, `storefront`, required)
  - `store` (Magento 2 object): `{code, type}` where type is `website` or `store`; required for storefront.
  - `base_url` (Magento 2 boolean): Choose this address for the store's base URLs; at most one per store.
- `default_store` (Magento 2 object or null): `{code, type}` for the default store, or null for Magento's default.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "aliases": {
      "description": "How non-canonical hosts are served: redirect or storefront. Magento 2: storefront needs store {code, type}; base_url chooses its base URL host.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "base_url": {
            "type": "boolean"
          },
          "host": {
            "maxLength": 253,
            "minLength": 1,
            "type": "string"
          },
          "serve": {
            "enum": [
              "redirect",
              "storefront"
            ],
            "type": "string"
          },
          "store": {
            "additionalProperties": false,
            "properties": {
              "code": {
                "maxLength": 32,
                "minLength": 1,
                "type": "string"
              },
              "type": {
                "enum": [
                  "website",
                  "store"
                ],
                "type": "string"
              }
            },
            "required": [
              "code",
              "type"
            ],
            "type": "object"
          }
        },
        "required": [
          "host",
          "serve"
        ],
        "type": "object"
      },
      "maxItems": 9,
      "minItems": 1,
      "type": "array"
    },
    "canonical": {
      "description": "The host the row is served on; one of hosts.",
      "maxLength": 253,
      "minLength": 1,
      "type": "string"
    },
    "confirm_domain": {
      "description": "The site's domain on the production row; the canonical host on any other row.",
      "maxLength": 253,
      "type": "string"
    },
    "confirm_replacements": {
      "description": "Allow the DNS plan to replace existing records.",
      "type": "boolean"
    },
    "default_store": {
      "additionalProperties": false,
      "description": "Magento 2: the default store, or null for Magento's default.",
      "properties": {
        "code": {
          "maxLength": 32,
          "minLength": 1,
          "type": "string"
        },
        "type": {
          "enum": [
            "website",
            "store"
          ],
          "type": "string"
        }
      },
      "required": [
        "code",
        "type"
      ],
      "type": [
        "object",
        "null"
      ]
    },
    "hosts": {
      "description": "The hosts to attach (production row: the site's domain or its www form among them; any other row: never it). A host-migration copy made under its provider's platform host may leave that name out (it can never point here).",
      "items": {
        "maxLength": 253,
        "minLength": 1,
        "type": "string"
      },
      "maxItems": 10,
      "minItems": 1,
      "type": "array"
    },
    "pending_dns": {
      "description": "Attach before DNS points at the platform (a migration's test of the copy): crons and outgoing mail stay held until the cutover. Each host that does not point here yet needs its TXT proof of control; a refusal names the record and its value. Not with point_dns.",
      "type": "boolean"
    },
    "point_dns": {
      "description": "Write the DNS plan through your company's Cloudflare connection.",
      "type": "boolean"
    },
    "proxied_records_checked": {
      "description": "The person has checked in Cloudflare that every host corestack_site_attach_domain_check lists in proxied_unconfirmed points at the platform's address. Ask them; never set it for them.",
      "type": "boolean"
    },
    "site_id": {
      "minimum": 1,
      "type": "integer"
    },
    "www": {
      "description": "Which form the other redirects to; default from canonical.",
      "enum": [
        "www",
        "bare"
      ],
      "type": "string"
    }
  },
  "required": [
    "site_id",
    "hosts",
    "canonical",
    "confirm_domain"
  ],
  "type": "object"
}
```

## Refusals

Store-choice refusals name `aliases.<n>.store`, where `n` is the alias's zero-based position, or `aliases` when its host
cannot be matched. Default-store refusals name `default_store`.

- `confirm_mismatch`: a typed confirmation does not match (`confirm_domain`: the site's domain on production, the canonical host elsewhere; `confirm_name`: the cluster's or environment's name); ask the person for the exact value.
- `provisioning`: the site is still being created; wait for corestack_site_provisioning_get to finish.
- `already_attached`: the row already serves its domain; change hosts with corestack_domains_update instead.
- `platform_plugins_off`: a WordPress production site whose platform plugins are turned off cannot go live, because they send the site's email from its verified address. Nothing was changed. Ask the person, turn them back on with corestack_site_platform_plugins_set (`enabled: true`, always allowed), follow the task it answers until it completes (the attach answers `busy` meanwhile), then attach again. corestack_site_attach_domain_check lists this in `blockers` first.
- `platform_plugins_applying`: the site's platform plugins are back on, but the platform has not finished applying that, so it cannot go live yet. Nothing was changed. Try again in a minute. If it stays, the last change failed: turn them on again with corestack_site_platform_plugins_set (`enabled: true`), which starts a new operation and answers its task, follow it until it completes, then attach again. corestack_site_attach_domain_check lists this in `blockers` too.
- `managed_elsewhere` (message: "This site is managed by another control panel"): another control panel manages this site, so use that control panel for it. This is refused before anything else about the site, as in the Control Panel and the API. Nothing was done.
- `invalid_arguments` on `hosts` ("<install>.wpengine.com is WP Engine's own address, which can never point here: attach the site's own domains."): a host under a migration provider's own platform domain (`*.wpengine.com`, `*.wpenginepowered.com`, `*.cloudwaysapps.com`); the site's own domain is the one exception. Nothing is written.
- 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).

- `store_hosts`: the site has platform store addresses managed by staff; contact support.
- `store_required`: `aliases.<n>.store` identifies the missing choice. Choose a Magento website or store view for every serving alias.
- `store_unknown`: `aliases.<n>.store` or `default_store` identifies the choice. Read the stores again and choose a code Magento lists.
- `store_inactive`: `aliases.<n>.store` or `default_store` identifies the choice. Switch the store view on in Magento or choose another.
- `store_code_format`: `aliases.<n>.store` or `default_store` identifies the choice. Use a Magento code with lower-case letters, digits or underscores, up to 32 characters.
- `store_host_not_served`: first add the address as an alias that shows its own store.
- `store_mapping_foreign`: the store rules are managed outside the Control Panel; contact support.
- `store_mapping_unreadable`: the existing store rules cannot be read safely; contact support.
- `nginx_rules_not_adopted`: the site's rules are not ready for this change; contact support.
- `nginx_rules_locked`: the site's rules are locked; contact support.
- `nginx_invalid`: the site's existing rules need attention before the store can be changed.
- `upstream_unavailable`: Magento's stores could not be read; try again in a moment.

## Example

```json
{
  "name": "corestack_site_attach_domain",
  "arguments": {
    "site_id": 4211,
    "hosts": [
      "example.co.uk",
      "guns.example.co.uk",
      "www.guns.example.co.uk"
    ],
    "canonical": "example.co.uk",
    "confirm_domain": "example.co.uk",
    "aliases": [
      {
        "host": "guns.example.co.uk",
        "serve": "storefront",
        "store": {
          "code": "guns",
          "type": "website"
        },
        "base_url": true
      },
      {
        "host": "www.guns.example.co.uk",
        "serve": "storefront",
        "store": {
          "code": "guns",
          "type": "website"
        }
      }
    ],
    "default_store": {
      "code": "base",
      "type": "website"
    }
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_site_attach_domain with site_id 4211, hosts ["example.co.uk","guns.example.co.uk","www.guns.example.co.uk"], canonical example.co.uk, aliases [{"host":"guns.example.co.uk","serve":"storefront","store":{"code":"guns","type":"website"},"base_url":true},{"host":"www.guns.example.co.uk","serve":"storefront","store":{"code":"guns","type":"website"}}], default_store {"code":"base","type":"website"}. (Attach a domain.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [POST /api/corestack/sites/{site}/attach-domain](https://docs.corefinity.com/api/reference/domains/attach-site-domain.md)
- Guide: [Add a domain](https://docs.corefinity.com/guides/sites/go-live/add-a-domain.md)
