MCP

Faceless ships a Model Context Protocol (MCP) server so agent runtimes (Claude Code, Claude Desktop, Cursor and any other MCP client) can call the API as tools. There are two ways to connect: the remote server over streamable HTTP, or a local stdio server. Both need an API key from your team settings at https://faceless.so/team.

Remote server (nothing to install)

The remote server lives at https://faceless.so/api/v1/mcp and speaks the streamable HTTP transport. Authenticate with the same Authorization header as the REST API.

Claude Code:

bash 
claude mcp add --transport http faceless https://faceless.so/api/v1/mcp \
  --header "Authorization: Bearer fl_live_..."

Any MCP client that supports streamable HTTP works the same way: point it at the URL and send Authorization: Bearer fl_live_... with every request.

Local server (stdio)

For clients that only speak stdio, run the server locally. Two equivalent ways: npx -y faceless-mcp, or faceless mcp if the CLI is installed. Both read the key from the FACELESS_API_KEY environment variable.

Claude Code:

bash 
claude mcp add faceless --env FACELESS_API_KEY=fl_live_... -- npx -y faceless-mcp

Claude Desktop (Settings > Developer > Edit Config, claude_desktop_config.json):

json 
{
  "mcpServers": {
    "faceless": {
      "command": "npx",
      "args": ["-y", "faceless-mcp"],
      "env": { "FACELESS_API_KEY": "fl_live_..." }
    }
  }
}

Cursor (.cursor/mcp.json in your project, or the global ~/.cursor/mcp.json):

json 
{
  "mcpServers": {
    "faceless": {
      "command": "npx",
      "args": ["-y", "faceless-mcp"],
      "env": { "FACELESS_API_KEY": "fl_live_..." }
    }
  }
}

Use the remote server when you want zero install and always-current tools; use the local one when your client only speaks stdio or your network policy prefers a locally spawned process.

Tools

All 27 API operations are exposed as tools named faceless_*, and each respects the key's scopes (a missing scope surfaces as a forbidden_scope error). The core ones an agent reaches for:

  • faceless_get_me, faceless_get_credits: identity, scopes and budget
  • faceless_list_voices, faceless_list_options: catalogs to choose voices, styles and models
  • faceless_create_video, faceless_get_video_status, faceless_render_video, faceless_get_render: the create, poll, render, poll lifecycle
  • faceless_create_caption_video: caption existing footage
  • faceless_update_video, faceless_publish_post, faceless_schedule_post, faceless_cancel_post, faceless_get_calendar: publishing and scheduling
  • faceless_create_series, faceless_list_series, faceless_get_series, faceless_update_series, faceless_delete_series, faceless_generate_series_episode, faceless_list_series_episodes: automated series
  • faceless_list_videos, faceless_get_video, faceless_delete_video, faceless_list_accounts, faceless_create_asset, faceless_get_analytics: the rest of the surface

Mutating tools accept an optional idempotencyKey argument with the same semantics as the REST Idempotency-Key header: retries with the same key and arguments replay the stored result instead of re-running (and re-charging). Pass one when a tool call might be retried.

Tool results use the same envelope and error types as the REST API; see errors and rate limits. Rate limits also apply per key, so a busy agent should back off on rate_limited.

Related

  • Prefer commands over tools? The CLI covers the same surface.
  • A packaged Claude Skill with ready-made workflows: npx skills add Side-Products/faceless-skill (https://github.com/Side-Products/faceless-skill).
  • The machine-readable surface: https://faceless.so/llms.txt and https://faceless.so/api/v1/openapi.json.