---
title: Operate Quirello through MCP
description: Read first, mutate through the Operator Contract, and recover from expected errors.
---

Use the Website-hosted `/q/mcp` endpoint for operator actions. Local requests do not require a token. Non-local requests require `Authorization: Bearer <QUIRELLO_OPERATOR_TOKEN>` and fail closed when that binding is absent.

## redirects

Read the exact source path with `quirello.redirect.get`, then call `quirello.redirect.upsert` with a site-relative source and destination:

```json
{
  "sourcePath": "/old-campaign",
  "destination": "/campaigns/current",
  "statusCode": 302
}
```

Use `quirello.redirect.delete` for an intentional removal. `quirello.redirect.sync-index` rebuilds the optional derived KV index. D1 remains canonical.

## forms and submissions

Read a definition with `quirello.form.get` before `quirello.form.upsert`. To inspect recent results, call `quirello.form-submission.list` with a form slug and optional ISO date-time bounds:

```json
{
  "formSlug": "contact",
  "start": "2026-07-01T00:00:00.000Z",
  "limit": 25
}
```

Public visitors submit through `POST /q/forms/:slug/submit`. Submission inspection stays on the authenticated Operator Contract.

## media

Media upload is three actions:

1. Call `quirello.media-upload.create-intent` with the filename, content type, and byte count.
2. Send the raw bytes with HTTP `PUT` to the returned Signed Upload URL.
3. Call `quirello.media-upload.finalize` with the returned asset id and object key.

The signed URL authorizes one byte transfer. It does not update metadata or finalize the asset. Use `quirello.media-asset.update-metadata` to retag an existing asset without sending its bytes again.

## recover

| Error | Next action |
| --- | --- |
| `invalid-input` | Correct the rejected input. Do not retry it unchanged. |
| `not-found` | Confirm the redirect path, form slug, or asset id. |
| `conflict` | Read the existing media id or choose an intentional overwrite policy. |
| `dependency-unavailable` | Restore the required host binding before retrying. |
| Transport failure | Confirm the MCP URL, host availability, and non-local bearer token. |

The [Operator Contract reference](/reference/operator-contract) is generated from the executable registry at build time. For a detailed end-to-end mutation, follow the [runnable redirect source tutorial](https://github.com/patronage/quirello/blob/main/src/tutorials/redirect.ts) and [its test](https://github.com/patronage/quirello/blob/main/src/tutorials/redirect.test.ts).