MCP server - Protoface

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 and a key from the dashboard. Export the key first:

export PROTOFACE_API_KEY="sk_live_..."

Install

Paste this into your agent and it installs itself:

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:

codex mcp add protoface --env PROTOFACE_API_KEY="$PROTOFACE_API_KEY" -- uvx protoface-mcp

claude mcp add --scope user --env PROTOFACE_API_KEY="$PROTOFACE_API_KEY" protoface -- uvx protoface-mcp

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "protoface": {
      "command": "uvx",
      "args": ["protoface-mcp"],
      "env": { "PROTOFACE_API_KEY": "${env:PROTOFACE_API_KEY}" }
    }
  }
}

Restart the agent, then ask:

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

---
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

Generate an 8-second video of a sailboat crossing a quiet bay at sunrise.

Find the cheapest image model and generate a 1024x1024 lighthouse with it.

Download the outputs of my most recent run to ./outputs/.

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. 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.
`[api_key.scope_required]`	The key needs `runs:read` and `runs:write`. See 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.
Run stays `queued`	`queue_position` counts the runs ahead of it. Keep polling; do not resubmit.
Other `[code]`	Every code is listed in Errors.

​Install

​Add the skill

​Example prompts

​Tools

​Troubleshooting

Install

Add the skill

Example prompts

Tools

Troubleshooting