> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: MCP Troubleshooting
sidebarTitle: Troubleshooting
description: Fix common issues connecting the Framer MCP plugin to AI assistants.
icon: lucide:wrench
---

# MCP troubleshooting

Solutions for the most common issues when connecting the **Framer MCP plugin** to AI assistants.

## Windows: URL with `&` breaks the command

**Symptom:** On Windows, the `&` in the MCP URL is interpreted as a command separator. You see errors like `'secret' is not recognized as an internal or external command`.

**Fix:** Wrap the entire URL in **double quotes** in your configuration:

```json
{
    "mcpServers": {
        "framer": {
            "url": "https://mcp.unframer.co/mcp?id=YOUR_ID&secret=YOUR_SECRET"
        }
    }
}
```

If you are using the `mcp-remote` bridge, wrap the URL in quotes in the args array:

```json
{
    "mcpServers": {
        "framer": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.unframer.co/mcp?id=YOUR_ID&secret=YOUR_SECRET"
            ]
        }
    }
}
```

## OAuth 404 / SSE 405 errors

**Symptom:** Claude Desktop shows `OAuth discovery on mcp.unframer.co returns HTTP 404` or `SSE fallback returns HTTP 405`.

**Fix:** These errors typically mean Claude Desktop is trying an **older MCP transport** that is not supported. Solutions:

1. **Use `mcp-remote` as a bridge.** This handles the transport negotiation for you:
   ```json
   {
       "mcpServers": {
           "framer": {
               "command": "npx",
               "args": [
                   "mcp-remote",
                   "https://mcp.unframer.co/mcp?id=YOUR_ID&secret=YOUR_SECRET"
               ]
           }
       }
   }
   ```

2. **Update Claude Desktop** to the latest version. Newer versions support StreamableHTTP transport natively.

3. If you have a **Claude Max subscription**, use the Connectors feature instead (Settings → Connectors → paste the MCP URL directly).

## WebSocket disconnects on write commands (error 1006/1001)

**Symptom:** Read operations (`getProjectXml`, `getNodeXml`) work fine, but write operations (`updateXmlForNode`) immediately disconnect with WebSocket error code 1006 or 1001.

**Fix:** This is usually a **network stability issue**. The write operations take longer and are more sensitive to connection drops.

1. **Close other browser extensions** that might interfere with WebSocket connections (ad blockers, privacy extensions, VPNs)
2. **Try a different network.** If you are on corporate WiFi, try a phone hotspot
3. **Restart the Framer desktop app** (not just the browser tab)
4. **Reconnect the MCP** in your AI tool settings after restarting
5. If the issue persists, try using **Server API mode** via the `unframer` CLI instead

<Aside>
  <Warning>
    Some **corporate firewalls** and proxy servers interfere with WebSocket connections. If you're on a managed network, ask your IT team about WebSocket policies.
  </Warning>
</Aside>

## Multi-account MCP conflicts

**Symptom:** You have two Framer accounts connected via MCP, but only the first one works. The second account shows as connected (green dot) but the AI says "Framer MCP plugin isn't currently connected."

**Fix:** The MCP identity is **per session**. Only one account can be active at a time.

1. **Disconnect the first account** from your AI tool entirely (remove the MCP server config)
2. **Close the MCP plugin** in the first account's Framer project
3. **Open the MCP plugin** in the second account's project
4. **Re-add the MCP server** in your AI tool with the second account's URL

You cannot use two Framer accounts simultaneously through MCP.

## Secret rotation / exposed URL

**Symptom:** Your MCP URL was accidentally shared (posted on GitHub, shared in a screenshot) and you want to revoke it.

**Fix:** Contact **[tommy@unframer.co](mailto:tommy@unframer.co)** with your MCP URL or Framer email. The session will be revoked within minutes.

After revocation:

1. Open the Framer MCP plugin
2. Log out and log back in
3. Copy the new MCP URL
4. Update your AI tool configuration with the new URL

<Aside>
  <Info>
    The MCP URL contains a **session secret** that grants access to your Framer project. Treat it like a password. Never commit it to public repositories.
  </Info>
</Aside>

## Connection timeouts

**Symptom:** The AI tool shows a timeout after 30-60 seconds when trying to connect.

**Fix checklist:**

1. **Is the Framer MCP plugin open?** The plugin must be open and showing a green status indicator
2. **Did you open the plugin BEFORE configuring the AI tool?** Some tools cache the connection state. Open the plugin first, then configure
3. **Are you using React Export?** Publishing is only needed for React Export or tools that read the published website URL. Canvas and CMS operations work without publishing
4. **Restart the MCP plugin.** Close it (click the X in Framer) and reopen it. This resets the WebSocket connection
5. **Restart your AI tool.** Cursor, Claude Desktop, etc. may need a restart to pick up config changes

## Cursor doesn't show Framer tools

**Symptom:** Cursor is configured but doesn't list Framer MCP in available tools.

**Fix:**

1. Make sure you have a **Cursor Pro subscription** (Agent mode requires Pro)
2. Enable **Agent mode** in Cursor settings
3. Check that the config file is in the right location: `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` globally
4. **Restart Cursor** after saving the config
5. Open the Agent panel and ask "What tools do you have available?"

## Quick diagnostic

If something isn't working, ask your AI assistant:

> Do you have access to the Framer MCP tool?

Then try a small read operation:

> Get the project structure

If reads work but writes fail, it is likely a network or timeout issue. If nothing works, the plugin is not connected or the URL is wrong.