MCP

Faceless ships a Model Context Protocol (MCP) server so agent runtimes (Claude, 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. The remote server accepts OAuth (sign in with your Faceless account, no key handling) or an API key from your team settings at https://faceless.so/team; the local server needs an API key.

Connect Claude (claude.ai and the Claude apps)

The fastest path for Claude users is a custom connector. No install, no API key: you sign in with your Faceless account and approve exactly the permissions you want. The same steps, with a copy button and a live "Connected" status, are in the app under Team settings > Claude & API (https://faceless.so/team?section=api).

Works on every Claude plan (the Free plan allows one custom connector). On Team and Enterprise plans an Owner adds the connector first in Organization settings > Connectors, then each member clicks Connect. Videos made from Claude use your team's credits, the same as in the app; when they run out, the tool error links to https://faceless.so/billing?tab=credits. Disconnect anytime from Team settings > Claude & API.

Faceless in the Claude directory

The Faceless connector listed in Claude's connector directory uses https://faceless.so/api/v1/mcp/claude. It signs in the same way (OAuth, you pick the team and permissions) and carries the tools for managing, rendering and publishing the videos you already have in Faceless:

Making new videos and buying credits are not part of this connector; do those in the Faceless app at https://faceless.so.

Try: "List my Faceless videos from this week", "Schedule my latest Faceless video to YouTube and TikTok for 6pm tomorrow" or "How did my Faceless posts do on TikTok over the last 30 days?".

Troubleshooting: a forbidden_scope error means the permission was unticked at sign-in, so disconnect and reconnect the connector and keep it ticked. A schedule_post rejection usually means the platform's post metadata is missing; set it with faceless_update_video first. Publishing needs the platform connected in Faceless (check with faceless_list_accounts). Anything else: [email protected].

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:

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:

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

Claude Desktop (Settings > Developer > Edit Config, claude_desktop_config.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):

{
	"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 32 API operations with an MCP tool 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:

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