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.

Available on Claude Pro, Max, Team and Enterprise plans. Access can be revoked anytime from your Faceless team settings.

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

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