> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subframe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect an external AI agent to Subframe and teach it how to design and implement with your project.

The Subframe MCP server gives AI coding assistants like Claude Code, Cursor, and Codex direct access to your Subframe projects. AI can read, design, and delete pages, components, and snippets, screenshot pages and components, read prototypes, write design documents, edit the theme, and search the Subframe docs.

A separate Subframe Docs MCP server gives AI access to Subframe documentation (this site).

## Installing the MCP server and Agent skills

<Tabs>
  <Tab title="Claude Code" icon="https://mintcdn.com/subframe-59800133/5lhHS3N1RqBy--k0/images/logos/claude.png?fit=max&auto=format&n=5lhHS3N1RqBy--k0&q=85&s=0328539c5fcb7c98c9d2ae793efe4387" width="48" height="48" data-path="images/logos/claude.png">
    <Steps>
      <Step title="Install the Subframe plugin">
        ```bash theme={null}
        claude plugin marketplace add https://github.com/SubframeApp/subframe && claude plugin install subframe@subframe
        ```

        The Subframe plugin for Claude Code sets up the MCP server and agent skills in one install.
      </Step>

      <Step title="Enable auto-update (recommended)">
        Keep the Subframe plugin up to date automatically:

        1. Run `/plugin` to open the plugin manager
        2. Select the **Marketplaces** tab
        3. Choose the **subframe** marketplace
        4. Select **Enable auto-update**
      </Step>

      <Step title="Verify installation">
        Run `/mcp` to check that the Subframe MCP server is connected, then try asking Claude Code to use Subframe.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop" icon="https://mintcdn.com/subframe-59800133/5lhHS3N1RqBy--k0/images/logos/claude.png?fit=max&auto=format&n=5lhHS3N1RqBy--k0&q=85&s=0328539c5fcb7c98c9d2ae793efe4387" width="48" height="48" data-path="images/logos/claude.png">
    <Steps>
      <Step title="Add the Subframe connector">
        1. Go to [**Customize > Connectors**](https://claude.ai/customize/connectors)
        2. Click <Icon icon="plus" size={16} /> and select **Add custom connector**
        3. Set the name to **Subframe**
        4. For **Remote MCP Server URL**, paste the following URL:
           ```
           https://mcp.subframe.com/mcp
           ```
        5. Click **Add**
      </Step>

      <Step title="Authenticate">
        Find the Subframe connector in your connectors list and click **Connect**. Follow the instructions on the Subframe website to complete authentication.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor" icon="https://mintcdn.com/subframe-59800133/5lhHS3N1RqBy--k0/images/logos/cursor.webp?fit=max&auto=format&n=5lhHS3N1RqBy--k0&q=85&s=b196ef73b2809e299d77151d18039541" width="72" height="72" data-path="images/logos/cursor.webp">
    <Steps>
      <Step title="Install MCP servers">
        Add the Subframe MCP servers to Cursor. You'll be prompted to authenticate via OAuth.

        * [Add Subframe MCP server to Cursor ↗](https://cursor.com/en-US/install-mcp?name=subframe\&config=eyJ1cmwiOiJodHRwczovL21jcC5zdWJmcmFtZS5jb20vbWNwIn0%3D)
        * (Optional) [Add Subframe Docs MCP server to Cursor ↗](https://cursor.com/en-US/install-mcp?name=subframe-docs\&config=eyJ1cmwiOiJodHRwczovL2RvY3Muc3ViZnJhbWUuY29tL21jcCJ9)

        <Accordion title="Troubleshooting: Manual installation">
          If the install links don't work, make the following changes to `~/.cursor/mcp.json`.

          ```json ~/.cursor/mcp.json theme={null}
          {
            "mcpServers": {
              "subframe": {
                "url": "https://mcp.subframe.com/mcp"
              },
              "subframe-docs": {
                "url": "https://docs.subframe.com/mcp"
              }
            }
          }
          ```

          Cursor will handle OAuth authentication automatically when you first connect.
        </Accordion>
      </Step>

      <Step title="Install agent skills">
        Agent skills are guided workflows that teach Cursor how to best use Subframe. Install them with:

        ```bash theme={null}
        npx skills add https://github.com/SubframeApp/subframe --skill '*' -g --agent cursor --yes
        ```
      </Step>

      <Step title="Verify installation">
        Check that the Subframe MCP server has successfully connected in **Cursor Settings** > **MCP**, then try asking Cursor to use Subframe.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex" icon="https://mintcdn.com/subframe-59800133/bS35JNxm1CpZNt1T/images/logos/openai.png?fit=max&auto=format&n=bS35JNxm1CpZNt1T&q=85&s=811e805e892ceea086cbc53c154c16b7" width="64" height="64" data-path="images/logos/openai.png">
    <Steps>
      <Step title="Install MCP servers">
        Run the following commands to add the Subframe MCP servers and authenticate:

        ```bash theme={null}
        codex mcp add subframe --url https://mcp.subframe.com/mcp && codex mcp add subframe-docs --url https://docs.subframe.com/mcp && codex mcp login subframe
        ```

        <Accordion title="Troubleshooting: Manual installation">
          If the commands above don't work, add the following to `~/.codex/config.toml`:

          ```toml ~/.codex/config.toml theme={null}
          [mcp_servers.subframe]
          url = "https://mcp.subframe.com/mcp"

          [mcp_servers.subframe-docs]
          url = "https://docs.subframe.com/mcp"
          ```

          Then authenticate:

          ```bash theme={null}
          codex mcp login subframe
          ```
        </Accordion>
      </Step>

      <Step title="Install agent skills">
        Agent skills are guided workflows that teach Codex how to best use Subframe. Install them with:

        ```bash theme={null}
        npx skills add https://github.com/SubframeApp/subframe --skill '*' -g --agent codex --yes
        ```
      </Step>

      <Step title="Verify installation">
        Run `/mcp` in Codex to check that the Subframe MCP server is connected, then try asking Codex to use Subframe.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Other clients">
    <Steps>
      <Step title="Configure the Subframe MCP Server">
        Configure your MCP client to connect to the Subframe MCP server:

        * **URL:** `https://mcp.subframe.com/mcp`
        * **Transport:** HTTP
        * **Authentication:** OAuth (your client will handle the authentication flow)
      </Step>

      <Step title="Configure the Subframe Docs MCP Server (optional)">
        Optionally add the Subframe Docs MCP server for documentation access:

        * **URL:** `https://docs.subframe.com/mcp`
        * **Transport:** HTTP
        * **Authentication:** None required
      </Step>

      <Step title="Install agent skills (optional)">
        If your client supports the [Agent Skills](https://agentskills.io) standard, install the Subframe skills with:

        ```bash theme={null}
        npx skills add https://github.com/SubframeApp/subframe --skill '*' --agent '*' --yes
        ```
      </Step>

      <Step title="Verify installation">
        Restart your MCP client, then check that the Subframe MCP server has successfully connected and try asking your AI assistant to use Subframe.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using Agent skills

Agent skills are guided workflows that teach your AI agent how to use Subframe. The MCP server gives the agent access to Subframe, while the skills teach it what to do with that access.

Subframe provides three skills:

* **`/subframe:design`** designs and edits pages, components, snippets, design documents, and themes in Subframe
* **`/subframe:develop`** implements a Subframe design in your codebase and adds the required application logic
* **`/subframe:install`** installs Subframe in a codebase and configures its theme, fonts, and components

Agent skills use the [Agent Skills open standard ↗](https://agentskills.io).

### Keeping Agent skills up to date

The Subframe plugin for Claude Code can update itself automatically. For Cursor, Codex, and other clients, check for updates with:

```bash theme={null}
npx skills check
```

Install available updates with:

```bash theme={null}
npx skills update
```

### Enabling the Claude Code plugin for your team

Add the following to `.claude/settings.json` so team members are prompted to install the Subframe plugin:

```json .claude/settings.json theme={null}
{
  "enabledPlugins": {
    "subframe@subframe": true
  },
  "extraKnownMarketplaces": {
    "subframe": {
      "source": {
        "source": "github",
        "repo": "SubframeApp/subframe"
      }
    }
  }
}
```

Commit this file to your repository.

## Using the MCP server

Once configured, your AI assistant can access Subframe automatically when you prompt or paste an MCP link to a page from the Code panel.

You can get the MCP link for any design by either:

* Copying the link from the browser address bar
* Copying the link under **Code** > **Inspect** in Subframe

<Frame>
  <img src="https://mintcdn.com/subframe-59800133/PZAsL35sSNLNRpRU/images/developers/copy-mcp-link.png?fit=max&auto=format&n=PZAsL35sSNLNRpRU&q=85&s=c348e8433c66e64ae2acd48ceb1cc3b1" alt="Copy MCP link from Subframe" width="584" height="81" data-path="images/developers/copy-mcp-link.png" />
</Frame>

## Available tools

The Subframe MCP server exposes tools across several categories. Most read tools take a `projectId`. If omitted, the first project the user has access to is used.

### Discovery

| Tool                  | Description                                   |
| --------------------- | --------------------------------------------- |
| `list_projects`       | List the projects you have access to          |
| `generate_auth_token` | Generate a CLI auth token for a team          |
| `get_project_info`    | Get project metadata and its design documents |
| `search_docs`         | Search the Subframe documentation             |

### Pages

| Tool              | Description                                          |
| ----------------- | ---------------------------------------------------- |
| `list_pages`      | List all pages and the flows they belong to          |
| `get_page_info`   | Get a page's generated React and Tailwind code       |
| `design_page`     | Generate new page designs from a description         |
| `edit_page`       | Edit a single element on a page                      |
| `screenshot_page` | Screenshot a page, a single element, or a breakpoint |
| `delete_page`     | Delete a page                                        |

### Components

| Tool                   | Description                                          |
| ---------------------- | ---------------------------------------------------- |
| `list_components`      | List all components                                  |
| `get_component_info`   | Get a component's generated code and design document |
| `screenshot_component` | Screenshot a component's variants and states         |
| `design_component`     | Design a new component from a description            |
| `edit_component`       | Edit a component, updating every page that uses it   |
| `delete_component`     | Delete a component or custom page layout             |

### Snippets

Snippets are small, standalone bits of UI typically embedded inside design documents as live examples (e.g. a "Button variants" snippet showing every Button state). They live within Subframe and do not sync out.

| Tool               | Description                                              |
| ------------------ | -------------------------------------------------------- |
| `list_snippets`    | List all snippets                                        |
| `get_snippet_info` | Get a snippet's generated code                           |
| `design_snippet`   | Design a new snippet from a description                  |
| `edit_snippet`     | Edit a single element in a snippet                       |
| `delete_snippet`   | Delete a snippet and remove it from any design documents |

### Flows

A flow is a collection of related pages (e.g. "Onboarding", "Checkout").

| Tool            | Description                                        |
| --------------- | -------------------------------------------------- |
| `list_flows`    | List all flows                                     |
| `get_flow_info` | Get a flow and its ordered pages                   |
| `delete_flow`   | Delete a flow, optionally with the pages inside it |

### Prototypes

A prototype is an interactive, AI-built running app — its own React + Vite codebase — created in the Subframe prototyping editor. The read tools below expose a prototype as a standalone, runnable Vite app: internal scaffolding is dropped and the Vite/Tailwind config plus an entrypoint are added, so the file paths and contents you get back are ready to run with `npm install && npm run dev`.

| Tool                  | Description                              |
| --------------------- | ---------------------------------------- |
| `list_prototypes`     | List all prototypes                      |
| `get_prototype_info`  | Get a prototype's metadata and file list |
| `read_prototype_file` | Read one file from a prototype           |

### Design documents

Design documents are markdown files that convey how to work within your design system — brand voice, design principles, component usage rules ("when to use Toggle vs. Checkbox"), accessibility requirements, do/don't examples. AI automatically reads them when designing or implementing. **Project-scoped** docs (many per project) cover broad guidance; **component-scoped** docs (one per component, attached directly to it) cover specifics for that component.

| Tool                    | Description                        |
| ----------------------- | ---------------------------------- |
| `write_design_document` | Create or update a design document |

A component can have at most one design document. Snippets can be embedded as live examples with `<div data-type="component-example" data-component-id="..."></div>`.

### Theme

| Tool           | Description                                                    |
| -------------- | -------------------------------------------------------------- |
| `get_theme`    | Get a project's themes, breakpoints, and available fonts       |
| `edit_theme`   | Edit a theme's colors, fonts, corners, shadows, and typography |
| `search_icons` | Search the project's icon library                              |

A project can hold several themes that share token names but differ in values. Theme edits apply immediately across every page and component.

<Warning>
  Deleting a theme token is destructive. Every reference to it in your designs is replaced with the token's value at
  deletion time, and those references stay detached even if you restore the token.
</Warning>

### Design references

The design tools can ground a generation in real material — an existing page, component, or snippet in your project, raw code from your codebase, or a mockup uploaded to Subframe. Each reference comes with a note telling the generator how to use it, like "Match this page's layout and header".

Invalid references are dropped with a warning in the tool result rather than failing the design.

### Async jobs

| Tool            | Description                               |
| --------------- | ----------------------------------------- |
| `wait_for_jobs` | Wait for background design jobs to finish |

`design_page`, `design_component`, and `edit_component` run in the background and return a URL you can open right away to watch progress in the editor. Reading a page or component back before its job finishes returns stale content.

## Prompting with an MCP link

To reference a page in an external agent, copy its MCP link from the Code panel.

```text theme={null}
Implement the design at https://app.subframe.com/design/...
```

<Note>
  To get the latest version of components in your project, run `npx @subframe/cli@latest sync` to [sync
  components](/develop/concepts/syncing-components).
</Note>

## Example prompts

<AccordionGroup>
  <Accordion title="Implement a new page from a design">
    ```text theme={null}
    Create a new page using the Subframe page at
    https://app.subframe.com/PROJECT_ID/design/DESIGN_ID/edit as reference.

    Wire up relevant app logic (API calls, hooks, routing) where applicable.
    Keep it consistent with existing project conventions.
    ```
  </Accordion>

  <Accordion title="Update an existing page with a new design">
    ```text theme={null}
    Update the existing page to match the Subframe design at
    https://app.subframe.com/PROJECT_ID/design/DESIGN_ID/edit.

    Preserve all existing functionality unless the new design requires a change.
    ```
  </Accordion>

  <Accordion title="Design a new component">
    ```text theme={null}
    Design a PrivacyToggle component in Subframe. It should have an on/off state,
    a label, and a description below the label. Use the same toggle styling as
    our existing Toggle component.
    ```
  </Accordion>

  <Accordion title="Write a design document">
    ```text theme={null}
    Write a design doc for the Toggle component covering when to use it,
    accessibility considerations, and a snippet showing all variants.
    ```
  </Accordion>

  <Accordion title="Delete unused components">
    ```text theme={null}
    List the components in my Subframe project and help me delete any that
    aren't being used in any pages.
    ```
  </Accordion>

  <Accordion title="Add accessibility tags in code">
    ```text theme={null}
    Review the Subframe design at
    https://app.subframe.com/PROJECT_ID/design/DESIGN_ID/edit and add proper
    accessibility attributes to the existing page.

    Add ARIA labels, roles, and descriptions, and proper semantic HTML throughout.
    ```
  </Accordion>

  <Accordion title="Migrate to Subframe's design system">
    ```text theme={null}
    Migrate the components on the existing page to use Subframe components instead
    of the old components.

    Get all components in my Subframe project and preserve all existing
    functionality unless the new design requires a change.
    ```
  </Accordion>

  <Accordion title="Fetch a component">
    ```text theme={null}
    Get the Button component from Subframe and use it in this file.
    ```
  </Accordion>

  <Accordion title="List available components">
    ```text theme={null}
    Show me all components in my Subframe project.
    ```
  </Accordion>

  <Accordion title="Get the theme">
    ```text theme={null}
    Get my Subframe theme configuration.
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    The Subframe MCP server uses OAuth. If you're seeing authentication errors:

    * Try re-authenticating by reconnecting to the MCP server in your client
    * Check that you have the correct permissions for the project you're trying to access
    * Make sure your browser session is active when authenticating
    * Confirm your client supports MCP OAuth — Subframe access tokens are not accepted by the MCP server
  </Accordion>

  <Accordion title="AI not calling the server">
    Make sure your AI tool:

    * Has MCP support enabled
    * Has the Subframe server in its MCP configuration
    * Has been restarted after adding the configuration

    Check your tool's logs for MCP-related errors.
  </Accordion>

  <Accordion title="Component or page not found">
    Use `list_components`, `list_pages`, `list_snippets`, or `list_flows` to see what's available.

    Verify:

    * The component/page/snippet exists in your Subframe project
    * The name or URL matches exactly
    * You have access to the project
  </Accordion>

  <Accordion title="Background job seems stuck">
    `design_page`, `design_component`, and `edit_component` run as background jobs. Check `wait_for_jobs` with the `jobId` returned by the design tool — it reports `running`, `done`, `error`, or `not_found`. The URL is live throughout, so opening it in the editor shows real-time progress.

    If a job stops reporting progress for \~10 minutes, the server treats it as stalled (worker died, request timed out) and reports it as `error` so polling never hangs — its summary explains that the result could not be verified. Open the URL to see whether anything was actually generated; the chat panel surfaces any errors from the AI agent.
  </Accordion>

  <Accordion title="Connection errors">
    If the MCP server is unreachable:

    * Check your internet connection
    * Verify the URL is `https://mcp.subframe.com/mcp`
    * Reach out to the Subframe team for support
  </Accordion>
</AccordionGroup>


## Related topics

- [Installation](/develop/installation.md)
- [Quickstart](/learn/quickstart.md)
- [Exporting code](/design/code-mode/overview.md)