> ## Documentation Index
> Fetch the complete documentation index at: https://subframe-59800133-gtmbot-restructure-dark-mode-docs-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Let AI coding assistants directly access your Subframe designs and documentation.

Our MCP server lets AI coding assistants like Claude Code, Cursor, and Codex access your Subframe designs directly. Instead of copying code manually, AI can fetch components, pages, and themes from your projects automatically.

We also have a separate Subframe Docs MCP server that provides access to Subframe documentation (this site).

## Installation

<Tabs>
  <Tab title="Claude Code" icon="https://mintcdn.com/subframe-59800133-gtmbot-restructure-dark-mode-docs-v2/GZlpuvApSd_ADHAr/images/logos/claude.png?fit=max&auto=format&n=GZlpuvApSd_ADHAr&q=85&s=582ae519a8b444f49d7a1c2bc31f467b" 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>

      <Step title="Create your first design">
        Follow the [Working with AI agents](/learn/guides/working-with-ai-agents) guide to design and implement your first page.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop" icon="https://mintcdn.com/subframe-59800133-gtmbot-restructure-dark-mode-docs-v2/GZlpuvApSd_ADHAr/images/logos/claude.png?fit=max&auto=format&n=GZlpuvApSd_ADHAr&q=85&s=582ae519a8b444f49d7a1c2bc31f467b" 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>

      <Step title="Create your first design">
        Follow the [Working with AI agents](/learn/guides/working-with-ai-agents) guide to design and implement your first page.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor" icon="https://mintcdn.com/subframe-59800133-gtmbot-restructure-dark-mode-docs-v2/GZlpuvApSd_ADHAr/images/logos/cursor.webp?fit=max&auto=format&n=GZlpuvApSd_ADHAr&q=85&s=6cd40765d2bea5f716de9c37b8d27872" 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>

      <Step title="Create your first design">
        Follow the [Working with AI agents](/learn/guides/working-with-ai-agents) guide to design and implement your first page.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex" icon="https://mintcdn.com/subframe-59800133-gtmbot-restructure-dark-mode-docs-v2/GZlpuvApSd_ADHAr/images/logos/openai.png?fit=max&auto=format&n=GZlpuvApSd_ADHAr&q=85&s=ffe19b434fcbcf47d215e6ce62e6a690" 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>

      <Step title="Create your first design">
        Follow the [Working with AI agents](/learn/guides/working-with-ai-agents) guide to design and implement your first page.
      </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>

      <Step title="Create your first design">
        Follow the [Working with AI agents](/learn/guides/working-with-ai-agents) guide to design and implement your first page.
      </Step>
    </Steps>

    ### Client doesn't support OAuth?

    Some clients (e.g. Antigravity) do not support OAuth for custom MCP servers. Instead, authenticate using a Subframe token passed as a header:

    1. Create a token at [**Settings > Access Tokens**](https://app.subframe.com/settings/tokens)
    2. Use the following MCP server configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "subframe": {
          "url": "https://mcp.subframe.com/mcp",
          "headers": {
            "Authorization": "Bearer <YOUR_SUBFRAME_TOKEN>"
          }
        },
        "subframe-docs": {
          "url": "https://docs.subframe.com/mcp"
        }
      }
    }
    ```

    You may need to restart your client or start a new conversation for it to pick up the configuration.
  </Tab>
</Tabs>

## 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-gtmbot-restructure-dark-mode-docs-v2/GZlpuvApSd_ADHAr/images/developers/copy-mcp-link.png?fit=max&auto=format&n=GZlpuvApSd_ADHAr&q=85&s=99daf74ca7d42d7b8784092f5d58737a" alt="Copy MCP link from Subframe" width="584" height="81" data-path="images/developers/copy-mcp-link.png" />
</Frame>

### Available tools

| Tool                  | Description                                                                                                                                                                                      | Input Parameters                                                                                                                                                    | Returns                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `list_projects`       | Lists all projects you have access to                                                                                                                                                            | —                                                                                                                                                                   | Array of projects with `projectId`, `name`, `teamId`, `teamName`                              |
| `generate_auth_token` | Generates a CLI auth token for a team                                                                                                                                                            | `teamId`                                                                                                                                                            | `authToken`                                                                                   |
| `list_components`     | Lists all components in your project                                                                                                                                                             | `projectId`                                                                                                                                                         | Array of components with `id`, `name`, `url`                                                  |
| `list_pages`          | Lists all pages in your project                                                                                                                                                                  | `projectId`                                                                                                                                                         | Array of pages with `id`, `name`, `url`                                                       |
| `get_component_info`  | Gets the code and metadata for a component                                                                                                                                                       | `id`, `name`, or `url`<br />`projectId`                                                                                                                             | `id`, `name`, `files`                                                                         |
| `get_page_info`       | Gets the code for a page                                                                                                                                                                         | `id`, `name`, or `url`<br />`projectId`                                                                                                                             | `id`, `name`, `files`                                                                         |
| `get_theme`           | Generates the Tailwind theme for the project                                                                                                                                                     | `projectId`<br />`cssType` (optional)                                                                                                                               | `theme` config                                                                                |
| `edit_theme`          | Updates the Tailwind theme for the project                                                                                                                                                       | `id`, `name`, or `url`<br />`projectId`                                                                                                                             | `editUrl`                                                                                     |
| `design_page`         | Designs UI pages in Subframe. Use to build new UI, iterate on existing UI, explore options, or get a visual starting point to refine.                                                            | `description`, `variations` (1, 2, or 4 objects with `name` and `description`), `flowName`<br />`projectId`, `codeContext` (optional), `additionalPages` (optional) | `pageId`, `reviewUrl`                                                                         |
| `edit_page`           | Edits an existing Subframe page. Use for targeted changes to an existing page. Describe the changes you want, optionally including code snippets for precision. The edit is applied immediately. | `id`, `name`, or `url`<br />`description`<br />`projectId`                                                                                                          | `pageUrl`                                                                                     |
| `get_variations`      | Gets the status and generated code for variations from a `design_page` call. Use to retrieve variation code for iterating on designs.                                                            | `pageId`                                                                                                                                                            | `status`, `currentPageCode` (string or null), `variations` (array of `name`, `state`, `code`) |

### Prompt with MCP link

When prompting we recommend using the MCP link found in the Code Inspect panel for a page.

```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](/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="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">
    Most clients authenticate via 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

    If your client doesn't support OAuth (e.g. Antigravity), authenticate using a Subframe token instead. Create a token at [**Settings > Access Tokens**](https://app.subframe.com/settings/tokens) and pass it as a header in your MCP configuration. See the [Other clients](#other-clients) installation tab for details.
  </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` or `list_pages` to see what's available.

    Verify:

    * The component/page exists in your Subframe project
    * The name or URL matches exactly
    * You have access to the project
  </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>