protoface-mcp

MCP server for Protoface media generation: discover models, submit async generation runs, and collect outputs — from Codex, Claude Code, Cursor, or any MCP client. 17 tools over the Protoface API; realtime sessions/avatars and website embeds are intentionally out of scope.

Install

Requires uv and a Protoface API key (create one).

Codex — add to ~/.codex/config.toml:

[mcp_servers.protoface]
command = "uvx"
args = ["protoface-mcp"]
env_vars = ["PROTOFACE_API_KEY"]

with PROTOFACE_API_KEY=sk_live_... exported in your shell.

Claude Code — add to .mcp.json (project) or ~/.claude.json (personal):

{
  "mcpServers": {
    "protoface": {
      "command": "uvx",
      "args": ["protoface-mcp"],
      "env": { "PROTOFACE_API_KEY": "sk_live_..." }
    }
  }
}

Then ask your agent to generate something:

Using Protoface, generate a 5-second video of a lighthouse at dusk.

The companion skill (skills/protoface-media/SKILL.md in this repo, published to the docs site) teaches agents the workflow: read the model's input schema first, check quota, submit, poll, collect outputs.

Tools

Run statuses: queued → running → completed / failed / canceled. Poll the cheap get_run_status, not get_run. Pass an idempotency_key to submit_run when retrying so a duplicate never double-spends.

Set PROTOFACE_BASE_URL to point at staging instead of https://api.protoface.com.

Development

uv run pytest packages/mcp        # drift + tool tests

tests/test_tool_coverage.py enforces spec parity: every media-generation operationId in apispec/openapi.json must have a tool. The wheel bundles the workspace SDK (protoface/...) so installs have no private dependencies — the protoface PyPI name belongs to an unrelated package, so it must never appear in dependencies.

Release: push a protoface-mcp-vX.Y.Z tag matching packages/mcp/pyproject.toml (see .github/workflows/publish-mcp.yml).