---
url: /orchestration/mcp.md
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# Civitai Orchestration MCP Server

The orchestrator is also a remote [Model Context Protocol](https://modelcontextprotocol.io) server. Any MCP client, such as Claude Desktop, claude.ai, Claude Code, Cursor or VS Code, can run the same workflows as the [REST API](https://developer.civitai.com/orchestration/guide/getting-started.md): images, video, audio, music, upscaling, conversion, tagging and every other step.

Instead of one tool per task, a few generic tools let the agent find a service, get its exact input, and run it, so new engines, models and steps appear without any change to the MCP server.

This is the **generation** MCP. To browse models and images, post, comment, react, or message on civitai.com, use the separate [Civitai (site) MCP](https://developer.civitai.com/site/mcp.md).

## Endpoint

```
https://orchestration.civitai.com/mcp/v2
```

Transport is **Streamable HTTP**, the MCP transport for remote servers. There is nothing to install; clients connect directly over HTTPS.

## Authentication

The MCP server uses the **same Civitai API key** as the [REST API](https://developer.civitai.com/orchestration/guide/authentication.md). Send it as a Bearer token in the `Authorization` header on every request:

The snippets on this page are pre-filled with the token you set in the navbar, or show a `YOUR_CIVITAI_API_KEY` placeholder. Requests without a valid token get `401`. Calls run as your account: Buzz is charged to it and workflows show up in `list_workflows`.

## Connecting

### Claude Desktop

Claude Desktop connects to a remote server as a **custom connector**, the same way as [claude.ai](#claude-ai) below. Its `claude_desktop_config.json` is for local (command-based) servers, not a remote URL.

### claude.ai

Add a custom remote MCP server under **Settings → Connectors → Add custom connector**:

* **URL:** `https://orchestration.civitai.com/mcp/v2`
* **Authentication:** custom header `Authorization` with the Bearer value below

### Claude Code, Cursor, VS Code

For Claude Code, run:

For Cursor or VS Code, add the same shape to your `mcp.json`:

### Other clients

Any client that speaks Streamable HTTP can connect: point it at `/mcp/v2` and send the `Authorization` header.

## Steps and services

* A **step** is what a workflow runs: `imageGen`, `videoGen`, `textToSpeech`, `convertImage` and so on. It's the `$type` in [`POST /v2/consumer/workflows`](https://developer.civitai.com/orchestration/reference/operations/SubmitWorkflow.md).
* A **service** is one concrete thing a step can do, meaning an engine, model and operation, identified like `image/flux2/klein/createImage/9b`. These are the same ids as [`GET /v2/services`](https://developer.civitai.com/orchestration/reference/operations/ListServices.md).

## How an agent uses it

1. **Pick a service.** `find_services` ranks services by speed, cost and success rate from a query like "fast cheap anime image", and prints each one's service id.
2. **Get its input.** `get_input_schema(service)` returns the JSON Schema for that service's input and an example to start from.
3. **Run it.** `run_step(stepType, input)`. Everything the service needs, the prompt included, goes inside `input`. To chain several steps, use `run_workflow(steps)`.

```jsonc
// get_input_schema({ "service": "image/flux2/klein/createImage/9b" })
{
  "service": "image/flux2/klein/createImage/9b",
  "stepType": "imageGen",
  "parameters": { "engine": "flux2", "model": "klein", "operation": "createImage", "modelVersion": "9b" },
  "schema": { "type": "object", "properties": { "width": { "minimum": 512, "maximum": 2048, "default": 1024 }, … } },
  "example": { "engine": "flux2", "model": "klein", "operation": "createImage", "modelVersion": "9b" }
}
```

To generate with Civitai checkpoints and LoRAs, pass their AIRs instead: `get_input_schema(resources=["urn:air:sdxl:checkpoint:civitai:257749@290640", …])` picks the service they run on and fills them into the example.

For jobs that take several steps, such as turning a generated picture into a video, `get_guide` returns a plan the agent can follow. The server's instructions tell the agent to use it.

Inputs are checked strictly: a property the step's schema doesn't define is rejected with the list of valid ones, so a guessed field name fails loudly instead of being ignored.

See the [tools reference](https://developer.civitai.com/orchestration/mcp/tools.md) for every tool, prompt and resource.

## Pricing, async submission, and tagging

`run_step`, `run_workflow`, `caption_media` and `transcribe_audio` accept four optional parameters:

| Parameter | Type | Behavior |
|---|---|---|
| `whatif` | boolean | Price the request without running it. Nothing is executed and no Buzz is spent, the same as `?whatif=true` on [`POST /v2/consumer/workflows`](https://developer.civitai.com/orchestration/reference/operations/SubmitWorkflow.md). |
| `waitForCompletion` | boolean | Default `true` (training steps default to `false`): the call returns when the workflow finishes. Set `false` to get the workflow ID back immediately and poll with `get_workflow`. |
| `tags` | string\[] | Up to 10 tags, 1–200 characters each, stored on the workflow. Filter by them later with `list_workflows`. |
| `metadataJson` | string | A JSON object (as a string) stored as the workflow's `metadata`. |

Results carry `structuredContent` alongside the text, so clients don't have to parse prose:

```jsonc
// whatif: true
{ "workflowId": "…", "cost": { "base": 12, "total": 12, "variable": false }, "insufficientBuzz": false, "currencies": ["blue"] }

// waitForCompletion: false
{ "workflowId": "…", "status": "submitted" }

// default (waits)
{ "workflowId": "…" }
```

`cost.variable` is `true` when the price is a cap that may settle lower. `currencies` lists the Buzz accounts the charge would draw from.

## Newer MCP clients

Clients on MCP protocol revision `2026-07-28` also get:

* **Buzz confirmation.** Before a run that costs Buzz, the server prices it and asks the user to approve, for example "Spend 12 Buzz to run imageGen?". If the user declines, nothing is spent. `whatif` calls and free runs skip the prompt.
* **Tasks.** A client that opts into the `io.modelcontextprotocol/tasks` extension gets a task back from the tools that run workflows instead of waiting for the result. The task ID is the workflow ID; poll it with `tasks/get` and stop it with `tasks/cancel`. Tasks don't depend on the connection, so a long video or training run can't time out the tool call.
* **Cached lists.** The tool and prompt lists may be cached for an hour.

Clients on earlier revisions work as described above, without these.

## Related

* [Tools, prompts, and resources](https://developer.civitai.com/orchestration/mcp/tools.md): the full catalog
* [Authentication](https://developer.civitai.com/orchestration/guide/authentication.md): how to get and rotate a Civitai API key
* [Recipes](https://developer.civitai.com/orchestration/recipes.md): REST examples for the same steps