---
title: "corestack_varnish_vcl_update"
url: https://docs.corefinity.com/mcp/tools/corestack_varnish_vcl_update
type: tool
last_updated: 2026-11-13
feature: varnish
related:
  - https://docs.corefinity.com/api/reference/varnish/replace-site-varnish-vcl.md
  - https://docs.corefinity.com/guides/sites/software-and-services/varnish.md
---
# corestack_varnish_vcl_update

**Change a site's custom Varnish VCL.** Saves custom Varnish VCL and applies it live; refused or failing VCL is put back automatically. Send the version from corestack_varnish_vcl_get. Validate first. Scope: write. Long-running: answers with a task.

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

## When to use it

Save custom Varnish VCL for a Magento 2 row and apply it live, with the `version` `corestack_varnish_vcl_get` answered. Read `corestack_varnish_policy_get` and check the VCL with `corestack_varnish_vcl_validate` first.

The save runs the policy and the compile check, records a new revision, commits it and Varnish loads it without dropping a request. The answer is a task on its `varnish_vcl_change` operation (follow it with `corestack_site_operation_get`): policy → compiled → loaded → checked. If Varnish refuses the VCL, or the site answers errors after it is loaded, the previous revision is put back automatically and the task ends with the reason; Varnish keeps serving the previous revision throughout. The revision's status in `corestack_varnish_vcl_history_list` moves from `saving` to `applied`, `rejected` or `rolled_back`.

The finished task's result carries `vcl`, what Varnish did with the revision, and so does `corestack_site_operation_get` for this operation at any time (the same object, also while it runs): `{revision, status, outcome, applied, applied_at, reason, warnings}`. `outcome` is `applied` (Varnish confirmed it), `pending_verify` (committed but not confirmed yet; it is checked again shortly, so read `corestack_varnish_vcl_history_list` later), `refused` (Varnish refused it; the previous revision is serving), `verify_failed` (the check after loading failed and the previous revision is being put back; read `corestack_varnish_vcl_history_list` until it says `rolled_back`) or `rolled_back` (the previous revision is confirmed back). `reason` says why. Only `applied: true` means the new VCL is live. A failed task carries the same `vcl` in its details.

While Varnish is switched off the VCL is checked and saved, and applies when Varnish is switched on: the answer is at once `{operation: {id, status_tool}, revision, applied: false, varnish_off: true}` (the operation only commits the files). Saving the content the row already has answers `{operation: null, revision: null}`. 20 saves and reverts a minute for each row, whoever sends them.

## Inputs

- `site_id` (integer, ≥ 1, required): the row, a Magento 2 site or one of its environments.
- `version` (integer, ≥ 0, required): the version from `corestack_varnish_vcl_get`; a newer save makes it stale.
- `hooks` (object, required): `recv`, `backend_response`, `deliver`, each text, or null or "" to empty it. A hook left out stays as it is.
- `note` (string, at most 200 characters): why, shown in the history.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "hooks": {
      "additionalProperties": false,
      "description": "Left out: unchanged; null or \"\": empty.",
      "properties": {
        "backend_response": {
          "maxLength": 49152,
          "type": [
            "string",
            "null"
          ]
        },
        "deliver": {
          "maxLength": 49152,
          "type": [
            "string",
            "null"
          ]
        },
        "recv": {
          "maxLength": 49152,
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "note": {
      "maxLength": 200,
      "type": "string"
    },
    "site_id": {
      "minimum": 1,
      "type": "integer"
    },
    "version": {
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "site_id",
    "version",
    "hooks"
  ],
  "type": "object"
}
```

## Refusals

- `stale`: someone saved since `version` was read; `details.version` is the current one. Read the VCL again with `corestack_varnish_vcl_get`.
- `vcl_invalid`: the policy refused the VCL; nothing was saved. `details.diagnostics` lists each problem with its hook, line, column and code.
- `vcl_compile_failed`: the VCL does not compile; nothing was saved. `details.diagnostics`.
- `vcl_locked`: Corefinity manages the VCL on this environment.
- `busy`: a save is already applying; try again when it ends.
- `varnish_not_offered`: the row is not a Magento 2 site.
- `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.
- 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": "corestack_varnish_vcl_update",
  "arguments": {
    "site_id": 4211,
    "version": 5,
    "hooks": {
      "backend_response": "if (bereq.url ~ \"^/size-guides/\") {\n    set beresp.ttl = 1d;\n}\n"
    },
    "note": "Cache the size guides for a day"
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_varnish_vcl_update with site_id 4211, version 5, hooks {"backend_response":"if (bereq.url ~ \"^/size-guides/\") {\n    set beresp.ttl = 1d;\n}\n"}, note Cache the size guides for a day. (Change a site's custom Varnish VCL.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [PUT /api/corestack/sites/{site}/varnish/vcl](https://docs.corefinity.com/api/reference/varnish/replace-site-varnish-vcl.md)
- Guide: [Varnish](https://docs.corefinity.com/guides/sites/software-and-services/varnish.md)
