---
title: "corestack_file_write"
url: https://docs.corefinity.com/mcp/tools/corestack_file_write
type: tool
last_updated: 2026-11-13
feature: files-and-transfers
related:
  - https://docs.corefinity.com/mcp/files-and-transfers.md
---
# corestack_file_write

**Write a file.** Write one file of the environment atomically (at most 1 MiB; base64 for binary). Pass expected_sha256 (or "absent" for a new file) to write only over the content you read: a different file answers content_changed. A link (e.g. a Git-mode shared wp-config.php) is followed and kept. The guarantee holds between MCP writes; other writers are detected only through expected_sha256. Scope: exec.

- Scope: `exec`
- Runs as a task: no

## When to use it

Write one file of the environment atomically (at most 1 MiB; base64 for binary). Pass expected_sha256 (or "absent" for a new file) to write only over the content you read: a different file answers content_changed. A link (e.g. a Git-mode shared wp-config.php) is followed and kept. The guarantee holds between MCP writes; other writers are detected only through expected_sha256.

## Inputs

- `site_id` (integer, ≥ 1, required)
- `path` (string, 1–1024 characters, required)
- `content` (string, up to 8388608 characters, required)
- `encoding` (one of `utf-8`, `base64`, default `"utf-8"`)
- `expected_sha256` (string, up to 64 characters): The SHA-256 of the file you read, or "absent".
- `mode` (string, up to 4 characters): Octal, e.g. 0644. Default: the existing file's, else 0644.
- `create_dirs` (boolean, default `false`)

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "content": {
      "maxLength": 8388608,
      "type": "string"
    },
    "create_dirs": {
      "default": false,
      "type": "boolean"
    },
    "encoding": {
      "default": "utf-8",
      "enum": [
        "utf-8",
        "base64"
      ],
      "type": "string"
    },
    "expected_sha256": {
      "description": "The SHA-256 of the file you read, or \"absent\".",
      "maxLength": 64,
      "type": "string"
    },
    "mode": {
      "description": "Octal, e.g. 0644. Default: the existing file's, else 0644.",
      "maxLength": 4,
      "type": "string"
    },
    "path": {
      "maxLength": 1024,
      "minLength": 1,
      "type": "string"
    },
    "site_id": {
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "site_id",
    "path",
    "content"
  ],
  "type": "object"
}
```

## Refusals

- `content_changed`: `corestack_file_write`'s `expected_sha256` no longer matches the file; read the file again and decide.
- `busy`: another change is running on this row; wait for it (corestack_site_operation_get) and call again.
- `ended_without_status`: an MCP command exited non-zero — any non-zero exit of a payload that was started, 125 included — ran out of time, ended without a status, or lost its container; status and exit code in `details`; read the output (`corestack_command_output_get`).
- `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_file_write",
  "arguments": {
    "site_id": 4211,
    "path": "/var/www/example.co.uk/htdocs/robots.txt",
    "content": "User-agent: *\nDisallow:\n"
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_file_write with site_id 4211, path /var/www/example.co.uk/htdocs/robots.txt, content User-agent: *
Disallow:
. (Write a file.) Tell me what it returned.
```

## The same task elsewhere

- Guide: [Files and transfers](https://docs.corefinity.com/mcp/files-and-transfers.md)
