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

Claude Code

1. Install the Subframe plugin

   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.

2. 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
3. Verify installation

   Run /mcp to check that the Subframe MCP server is connected, then try asking Claude Code to use Subframe.

4. Create your first design

   Follow the Working with AI agents guide to design and implement your first page.

Claude Desktop

1. Add the Subframe connector

   1. Go to Customize > Connectors
   2. Click 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
2. Authenticate

   Find the Subframe connector in your connectors list and click Connect. Follow the instructions on the Subframe website to complete authentication.

3. Create your first design

   Follow the Working with AI agents guide to design and implement your first page.

Cursor

1. Install MCP servers

   Add the Subframe MCP servers to Cursor. You’ll be prompted to authenticate via OAuth.

   • Add Subframe MCP server to Cursor ↗
   • (Optional) Add Subframe Docs MCP server to Cursor ↗

   Troubleshooting: Manual installation

   If the install links don’t work, make the following changes to ~/.cursor/mcp.json.

   ~/.cursor/mcp.json

   {
     "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.

2. Install agent skills

   Agent skills are guided workflows that teach Cursor how to best use Subframe. Install them with:

   npx skills add https://github.com/SubframeApp/subframe --skill '*' -g --agent cursor --yes
   
3. Verify installation

   Check that the Subframe MCP server has successfully connected in Cursor Settings > MCP, then try asking Cursor to use Subframe.

4. Create your first design

   Follow the Working with AI agents guide to design and implement your first page.

Codex

1. Install MCP servers

   Run the following commands to add the Subframe MCP servers and authenticate:

   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
   

   Troubleshooting: Manual installation

   If the commands above don’t work, add the following to ~/.codex/config.toml:

   ~/.codex/config.toml

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

   Then authenticate:

   codex mcp login subframe
   
2. Install agent skills

   Agent skills are guided workflows that teach Codex how to best use Subframe. Install them with:

   npx skills add https://github.com/SubframeApp/subframe --skill '*' -g --agent codex --yes
   
3. Verify installation

   Run /mcp in Codex to check that the Subframe MCP server is connected, then try asking Codex to use Subframe.

4. Create your first design

   Follow the Working with AI agents guide to design and implement your first page.

Other clients

1. 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)
2. 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
3. Install agent skills (optional)

   If your client supports the Agent Skills standard, install the Subframe skills with:

   npx skills add https://github.com/SubframeApp/subframe --skill '*' --agent '*' --yes
   
4. 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.

5. Create your first design

   Follow the Working with AI agents guide to design and implement your first page.

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
2. Use the following MCP server configuration:

{
  "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.

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

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 projectId	id, name, files
get_page_info	Gets the code for a page	id, name, or url projectId	id, name, files
get_theme	Generates the Tailwind theme for the project	projectId cssType (optional)	theme config
edit_theme	Updates the Tailwind theme for the project	id, name, or url 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 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 description 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.

Implement the design at https://app.subframe.com/design/...

To get the latest version of components in your project, run npx @subframe/cli@latest sync to sync components.

Example prompts

Implement a new page from a design

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.

Update an existing page with a new design

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.

Add accessibility tags in code

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.

Migrate to Subframe's design system

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.

Fetch a component

Get the Button component from Subframe and use it in this file

List available components

Show me all components in my Subframe project

Get the theme

Get my Subframe theme configuration

Troubleshooting

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 and pass it as a header in your MCP configuration. See the Other clients installation tab for details.

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.

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

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