> For the complete documentation index, see [llms.txt](https://docs.trezalabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trezalabs.com/api/mcp-server.md).

# MCP Server

Treza ships a remote [Model Context Protocol](https://modelcontextprotocol.io/) server, so AI assistants like Claude can list your pipelines, inspect runs, and start new runs on your behalf.

```
https://trezalabs.com/api/mcp
```

The server speaks Streamable HTTP and authenticates every request. You can connect with OAuth (sign in with your Treza account, no key handling) or with an API key.

***

## Connect from claude.ai

Claude's web and desktop apps support custom connectors:

1. Open **Settings → Connectors → Add custom connector**.
2. Enter a name (for example, `Treza`) and the URL `https://trezalabs.com/api/mcp`. Leave the OAuth fields empty.
3. Click **Add**, then **Connect**. You'll be sent to Treza to sign in and approve access, then returned to Claude.

That's it. Ask Claude things like "list my Treza pipelines" or "run my daily short pipeline and tell me when it finishes."

***

## Connect from Claude Code

```bash
claude mcp add --transport http treza https://trezalabs.com/api/mcp
```

Claude Code discovers the OAuth flow automatically and opens a browser window to sign in. To use an [API key](/api/api-keys.md) instead:

```bash
claude mcp add --transport http treza https://trezalabs.com/api/mcp \
  --header "Authorization: Bearer treza_live_..."
```

Any other MCP client that supports Streamable HTTP works the same way: point it at the URL, and either complete the OAuth flow or send your key as a bearer token.

***

## Authentication and scopes

| Method  | How                                                         | Scopes                            |
| ------- | ----------------------------------------------------------- | --------------------------------- |
| OAuth   | Sign in with your Treza account when the client prompts you | `pipelines:read`, `pipelines:run` |
| API key | `Authorization: Bearer treza_live_...` header               | Whatever the key was granted      |

API keys must carry the `pipelines:read` scope to connect, and `pipelines:run` to start runs. Grant scopes when you create the key on the **API keys** page. See [API Keys](/api/api-keys.md).

Access is account-scoped either way: the server only ever sees pipelines owned by the signed-in account, and requests for anything else return an error.

***

## Available tools

| Tool             | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `list_pipelines` | List your pipelines with status and a summary of recent runs     |
| `get_pipeline`   | One pipeline's metadata plus a summary of its node graph         |
| `list_runs`      | Recent runs for a pipeline, newest first                         |
| `get_run`        | One run's status, per-node results, and output media URLs        |
| `run_pipeline`   | Start a run in the background and return its `runId` immediately |

***

## Runs are asynchronous

Video generation takes minutes, so `run_pipeline` never blocks. It starts the run on Treza's background workers and returns a `runId` right away; the assistant then polls `get_run` until the status is no longer `running`. Finished runs include output URLs for the generated media.

{% hint style="warning" %}
Runs started over MCP are real runs: they draw from your prepaid credit balance and appear in run history, exactly like runs started from the dashboard or the [Pipeline API](/api/pipeline-api.md).
{% endhint %}

***

## Related

* [API Keys](/api/api-keys.md) - create a key with `pipelines:*` scopes.
* [Pipeline API](/api/pipeline-api.md) - call a published pipeline over plain HTTP.
* [Build your first pipeline](/pipelines/quickstart.md) - end-to-end from the canvas.