MCP Overview

The Faces MCP (Model Context Protocol) server lets AI assistants like Claude build interactive, explorable decks slide by slide. Your assistant writes each slide’s code directly, without using any credits.

​

What is MCP?

MCP is an open protocol that lets AI assistants connect to external tools. When you connect Claude to the Faces MCP server, Claude can:

• Create a blank project to start a new presentation (in your personal team or any team you belong to)
• List the teams you belong to so the assistant can pick the right one
• List and browse your existing projects (including team-shared projects)
• Read and edit individual slides: inspect slide source files and write new ones. Works for any project where you are the owner, a team member (on team-shared projects), or an invited editor
• Set the project’s design system: the palette and fonts shared across every slide
• Attach plugins to a slide, such as a contact form or a live AI video presenter
• Screenshot a slide to visually verify layout, spacing, and typography after editing
• Publish or unpublish a project and read its live URL

There is no server-side “generate a full presentation” tool exposed through MCP. The assistant itself authors every slide. To build a new deck, it creates a blank project and then fills in slides one at a time.

​

Available tools

​

Session & agent mode

Tool	Description
get_user_state	Read your live editor state across open browser tabs: the project you’re viewing, the selected slide, and whether agent mode is on. The assistant calls this first to know which project you’re working on.
start_agent_mode	Turn on “agent mode” for a project in your browser: hides the right sidebar and shows a floating bar indicating an agent is driving the session. Pass enabled: false to turn it off. You can always deactivate it manually.

​

Teams

Tool	Description
list_teams	List the teams you belong to. Returns id, slug, name, role, and isPersonal. Use the team id when calling create_project.

​

Projects

Tool	Description
create_project	Create a new blank project. Returns the projectSlug and editorUrl. Accepts an optional teamId; omit it to use your personal team, or pass an id from list_teams to create the project under a specific team.
list_projects	List projects you can access (owned, team-shared, or shared with you) with pagination (cursor, limit, published).
get_project	Get project details and URLs for a given slug.
rename_project	Rename a project. The slug and URLs stay the same.
duplicate_project	Create a full copy of a project, including all slides. Returns a new projectSlug and editorUrl.

​

Design system

Tool	Description
get_project_config	Read project.config.json, including layout settings and the shared design system tokens (palette colors and fonts) used across every slide.
update_project_config	Update project.config.json, for example to define the project’s palette and fonts before styling slides. Only the keys you pass are changed.

​

Publishing

Tool	Description
publish_project	Publish a project’s latest version, making it publicly accessible. Returns the publishedUrl.
unpublish_project	Take a published project offline. The project and its slides are kept.
get_project_url	Get a project’s current live URL (subdomain or custom domain plus path) and the subdomains and domains available to switch to.

​

Slides

Tool	Description
list_slides	List all slides in a project. Returns slide IDs and names.
get_slide	Read a slide’s source files (face.tsx, face.content.json, face.controls.json).
create_slides	Create one or more empty slides in order in a single atomic call. Returns the new slideIds in the same order. Pass editing: true to show the loading gradient on every new slide immediately.
reorder_slides	Reorder every slide in a project in a single atomic call. Pass the full list of existing slideIds in the desired final order. Use this to restructure an existing deck; never delete and recreate slides just to reorder them.
update_slide	Update a slide’s source files. Validates and compiles before saving; returns errors if the code doesn’t compile.
start_slide_editing	Show the loading gradient in the editor before making edits.
finish_slide_editing	Clear the loading gradient after editing (always call, even on failure).
view_slide	Take a screenshot of a slide and return it as an image so the assistant can visually verify layout, spacing, and typography. Pass isMobile: true for the mobile layout.
get_slide_guide	Get the full slide authoring reference (file formats, block types, controls, typography, examples). Call before writing slide code for the first time.

​

Plugins

Tool	Description
list_plugins	List the plugins available to attach to a slide: runtime behaviors a slide’s code can’t express on its own, such as collecting form submissions or embedding a live AI video presenter.
get_plugin_docs	Fetch a plugin’s config schema, the functions it exposes, and code examples showing how a slide calls it. Read this before setup_plugin.
setup_plugin	Configure a plugin instance on a slide. The config is validated against the plugin’s schema and written to the slide’s face.plugins.json; other instances are preserved.

​

Building a new presentation

1. get_slide_guide: read the authoring reference (first time only)
2. (Optional) list_teams: if the user might want the project in a specific team, list them and ask. Otherwise skip and the personal team will be used.
3. create_project({ name, teamId? }): returns projectSlug and editorUrl
4. (Recommended) update_project_config({ projectSlug, config }): define the shared design system (palette and fonts) before styling slides, so every slide stays consistent.
5. create_slides({ projectSlug, slides: [{ name }, ...], editing: true }): ONE call with every slide you plan to add, in order. Returns the new slideIds. Never call this in a loop or in parallel for the same project.
6. For each returned slideId (in parallel or sequentially):
   1. update_slide({ projectSlug, slideId, files }): writes face.tsx, face.content.json, face.controls.json
   2. view_slide({ projectSlug, slideId }): screenshot the slide to verify it renders as intended
   3. finish_slide_editing({ projectSlug, slideId }): clears the loading gradient
7. Share the editorUrl with the user.

​

Editing an existing slide

1. (Optional) get_user_state: discover which project and slide the user currently has open
2. get_slide_guide: if you haven’t read it yet
3. start_slide_editing(slideId)
4. get_slide(slideId): read current files
5. update_slide(slideId, files)
6. view_slide(slideId): verify the result visually
7. finish_slide_editing(slideId)

​

Authentication

The MCP server uses OAuth for authentication. When you first connect, you’ll be prompted to sign in to your Faces account through your browser. No API key management needed; the OAuth flow handles everything automatically. Because MCP is authenticated per-account (not per-team), new projects default to your personal team unless the assistant passes an explicit teamId from list_teams. This differs from the REST API and CLI, which authenticate with team-scoped API keys and always create projects under the key’s team. (For the CLI, the team is chosen at faces login --team <slug-or-id>; for REST API keys, at Settings > Developers in the dashboard.)

​

Access control

The MCP tools respect the same permission model as the rest of Faces:

• Project owner: full read/write access.
• Team-shared projects: any member of the owning team can read and edit.
• Invited collaborators: can read; only collaborators with edit permission can update slides.

If the signed-in user does not have access to a project, the MCP tools return “Project not found or you don’t have access”.