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

# MCP server

> Generate media from Codex, Claude Code, or Cursor.

`protoface-mcp` is an MCP server for the media generation API. It runs on
your machine through `uvx` and authenticates with your API key. It covers
models, runs, and assets. Realtime sessions and avatars are not included.

You need [uv](https://docs.astral.sh/uv/) and a key from the
[dashboard](https://app.protoface.com). Export the key first:

```bash theme={null}
export PROTOFACE_API_KEY="sk_live_..."
```

## Install

Paste this into your agent and it installs itself:

```text theme={null}
Install the Protoface MCP server. It is a stdio server: the command is
`uvx protoface-mcp` and it needs the environment variable PROTOFACE_API_KEY,
which is already set in my shell. Register it under the name "protoface"
at user scope, then call its list_models tool to confirm it works.
```

Or run one command:

<CodeGroup>
  ```bash Codex theme={null}
  codex mcp add protoface --env PROTOFACE_API_KEY="$PROTOFACE_API_KEY" -- uvx protoface-mcp
  ```

  ```bash Claude Code theme={null}
  claude mcp add --scope user --env PROTOFACE_API_KEY="$PROTOFACE_API_KEY" protoface -- uvx protoface-mcp
  ```

  ```json Cursor theme={null}
  // ~/.cursor/mcp.json
  {
    "mcpServers": {
      "protoface": {
        "command": "uvx",
        "args": ["protoface-mcp"],
        "env": { "PROTOFACE_API_KEY": "${env:PROTOFACE_API_KEY}" }
      }
    }
  }
  ```
</CodeGroup>

Restart the agent, then ask:

```text theme={null}
List the Protoface models and my credit balance.
```

## Add the skill

The server exposes tools. The skill below tells the agent the order to
call them in, and it is the same file for every client. Save it as
`SKILL.md`:

| Client | Path |
| - | - |
| Codex | `~/.agents/skills/protoface-media/SKILL.md` |
| Claude Code | `~/.claude/skills/protoface-media/SKILL.md` |
| Cursor | `.cursor/skills/protoface-media/SKILL.md` in the project |

```markdown theme={null}
---
name: protoface-media
description: Generate images, video, and audio with Protoface models. Use when the user wants to create media, check generation status, download results, or manage generation assets and spend.
---

# Protoface media generation

Requires the `protoface` MCP server and a `PROTOFACE_API_KEY`. If the tools
are missing, point the user to https://docs.protoface.com/reference/mcp.

## Generating

Every model has its own input schema. Do not guess a payload.

1. `list_models`, then `get_model` on the one you want. Read
   `request_schemas` (one JSON schema per operation), `operations`, and
   `pricing`. If a model has several operations, ask which one.
2. If the payload needs files, `upload_asset` each one first and reference
   the returned asset ids.
3. `get_quota_limits` before anything large. State the expected cost.
4. `submit_run` with a payload that matches the schema. On any retry, reuse
   the same `idempotency_key` so the run is not charged twice.
5. Poll `get_run_status` every few seconds until the status is terminal.
   It is cheaper than `get_run`. `list_run_events` with `after` shows
   progress on long runs.
6. `get_run` for `outputs[]`. Each entry has `type`: `asset` (a `file.url`
   and an `asset_id`), `text`, or `data`. `download_asset` writes an asset
   to disk.

## Statuses

`queued` (see `queue_position`) and `running` (see `progress`, 0–100) are
in flight. `completed`, `failed` (see `error`), and `canceled` are final.
Do not poll a final run.

## Errors

Tool errors start with a stable code in brackets, such as
`[quota.exceeded]`. Branch on the code. On auth errors ask the user to
check `PROTOFACE_API_KEY`. On quota errors report `get_quota_limits` and
stop.

## Scope

Media generation only. Realtime sessions, avatars, and embeds are separate
APIs; send the user to https://docs.protoface.com rather than improvising.
```

## Example prompts

```text theme={null}
Generate an 8-second video of a sailboat crossing a quiet bay at sunrise.
```

```text theme={null}
Find the cheapest image model and generate a 1024x1024 lighthouse with it.
```

```text theme={null}
Download the outputs of my most recent run to ./outputs/.
```

```text theme={null}
How many credits do I have left, and what did I spend this month?
```

## Tools

| Group | Tools |
| - | - |
| Runs | `submit_run`, `get_run_status`, `get_run`, `cancel_run`, `list_runs`, `list_run_events` |
| Models | `list_models`, `get_model` |
| Assets | `upload_asset`, `list_assets`, `get_asset`, `download_asset`, `delete_asset` |
| Account | `get_usage_summary`, `list_billing_plans`, `get_quota_limits`, `get_status` |

Each tool maps to one endpoint in the [API Reference](/api-reference/index).
`submit_run` holds the credit estimate when the run is accepted. A cancel
that lands after the run has started does not refund the work done.
Uploads are capped at 100 MB per file.

## Troubleshooting

| Symptom | Fix |
| - | - |
| `PROTOFACE_API_KEY is not set` | Export the key in the shell that launches the agent, then restart it. |
| `[api_key.unknown]` | The key is wrong or revoked. Create a new one in the [dashboard](https://app.protoface.com). |
| `[api_key.scope_required]` | The key needs `runs:read` and `runs:write`. See [Authentication](/guides/authentication). |
| `[model.not_found]` | Call `list_models`; ids are exact and the catalog changes. |
| `[connection_error]` | Network problem between your machine and the API. Check [status](https://status.protoface.com). |
| Run stays `queued` | `queue_position` counts the runs ahead of it. Keep polling; do not resubmit. |
| Other `[code]` | Every code is listed in [Errors](/reference/errors). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.