> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sigmora.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Drive Sigmora from Claude, Cursor or any MCP client, with the same API key.

Sigmora runs an [MCP](https://modelcontextprotocol.io) server, so an assistant
you already use can work inside your workspace instead of you copying results
between tabs.

It is not a second product with its own login, and it is not a smaller version
of the API: it takes the **same `sk_live_` key**, answers on the **same host**,
runs the **same handlers**, and bills the **same balance**. Every endpoint in the
[API reference](/api-reference) is a tool.

## Connect

```json theme={null}
{
  "mcpServers": {
    "sigmora": {
      "url": "https://api.sigmora.org/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}
```

Mint the key in **Settings → API keys** in any workspace you belong to. Transport
is Streamable HTTP (JSON-RPC 2.0, protocol revision `2025-06-18`); a Firebase ID
token works too, for first-party clients.

<Note>
  `https://docs.sigmora.org/mcp` is a **different** server — this documentation
  site's own, which searches these pages. The one above does the work.
</Note>

## Tool names

A tool is named for its operation, with the dot replaced by an underscore.

| Endpoint                   | Tool              |
| -------------------------- | ----------------- |
| `POST /v1/text/script`     | `text_script`     |
| `POST /v1/video/edit`      | `video_edit`      |
| `POST /v1/image/thumbnail` | `image_thumbnail` |

The tool list, its request schemas and its prices are generated from the same
catalogue this documentation is generated from, so `tools/list` and the reference
cannot disagree. Prices are also live in `capabilities_list`.

## Start here, not with a capability

Every capability requires a `projectId` — the container its output is filed in.
Call `projects_create` first.

| Tool                             | What it does                                                                  |
| -------------------------------- | ----------------------------------------------------------------------------- |
| `projects_create`                | Make a container. **The first call in any sequence.**                         |
| `projects_list` · `projects_get` | Find existing work, and read what a call produced                             |
| `jobs_get`                       | Poll an async capability. Every job converges here, whatever produced it      |
| `capabilities_list`              | Live prices, this deployment's credit balance, and what it can actually serve |
| `usage_get`                      | Consumption by endpoint, key and day                                          |

## Two differences from HTTP

A tool call carries arguments, not headers, so two things that are headers over
HTTP are arguments here. Everything else — auth, prices, error codes, project
scoping, job polling — is identical, because it is the same code underneath.

| Over HTTP                  | Over MCP                                                            |
| -------------------------- | ------------------------------------------------------------------- |
| `Idempotency-Key: <id>`    | an `idempotencyKey` argument                                        |
| `X-Workspace-Slug: <slug>` | an optional `workspace` argument (omit it — your key names its own) |

## Agents and research

The same server also carries the workspace's autonomous agents, which have no
REST equivalent:

| Tool                                         | What it does                                                  |
| -------------------------------------------- | ------------------------------------------------------------- |
| `list_agents` · `get_agent` · `create_agent` | Read and create the autonomous agents in a workspace          |
| `run_agent` · `get_run_status` · `list_runs` | Start a run and follow it                                     |
| `score_video_metadata`                       | Score a title/description/tag package before you commit to it |
| `research_youtube_keyword`                   | Keyword research                                              |
| `audit_youtube_channel`                      | Audit a public channel                                        |

`create_agent` defaults to draft-only autonomy: it produces drafts and publishes
nothing without review.

## If you are the agent reading this

Four things that are easy to get wrong and expensive to get wrong:

* **Spending is real.** Every capability call debits a human's credit balance and
  cannot be undone once it succeeds. Confirm before a batch.
* **Retry with `idempotencyKey`.** A repeat with the same id and the same
  arguments replays the stored result instead of doing — and charging for — the
  work twice. The same id with different arguments is refused, not answered.
* **An async tool hands you a job id, not an answer.** Read it with `jobs_get`
  until `status` is `done` or `failed`.
* **`awaiting_review` is a person, not a delay.** Polling will never advance it.
  Tell the user instead of waiting.

[`llms.txt`](https://docs.sigmora.org/llms.txt) is the same material in one plain
file, if you would rather read the whole map at once.