Claude Desktop Remote MCP Server Configuration Documentation Error

[thomivy]

Claude Desktop Remote MCP Server Configuration Documentation Error

Summary

The current Webflow MCP documentation instructs users to configure the remote server via claude_desktop_config.json, but this method does not work with Claude Desktop. Remote MCP servers must be added through the Claude Desktop UI (Settings > Connectors), not via the config file.

Current Documentation Issue

Location: https://developers.webflow.com/data/docs/getting-started

Current Instructions (Incorrect):
The documentation currently instructs users to add the following to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "webflow": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.webflow.com/sse"]
    }
  }
}

Why This Doesn't Work

According to Claude's official documentation:

Claude Desktop will NOT connect to remote servers configured directly via claude_desktop_config.json. Remote MCP servers must be added through Settings > Connectors instead.

The claude_desktop_config.json file is only for local MCP servers (those running on the user's machine via stdio). Remote servers require a different configuration path.

Evidence

When attempting to connect using the config file method, Claude Desktop logs show:

[info] MCP Server connection requested for: webflow
[info] Launching MCP Server: webflow
[info] Shutting down MCP Server: webflow
[warn] UtilityProcess Check: Extension webflow not found in installed extensions
[info] [EventLogging] Event logged successfully: desktop_mcp_unexpected_close

Claude Desktop treats "webflow" as a missing local extension rather than recognizing it as a remote server configuration. No OAuth flow is triggered, and the connection fails immediately.

Correct Approach

Users should be instructed to:

1. Remove any Webflow entries from claude_desktop_config.json (if previously added)
2. Open Claude Desktop
3. Navigate to Settings > Connectors
4. Add the remote server URL: https://mcp.webflow.com/sse
5. Complete the OAuth authorization flow when prompted

The mcp-remote bridge is not needed when using the Settings UI approach - Claude Desktop handles the remote connection directly.

Suggested Documentation Update

Option 1: Settings UI Only (Recommended)

Update the documentation to instruct users to add Webflow via Settings > Connectors exclusively, as this is the officially supported method for remote MCP servers.

Option 2: Clarify Both Methods

If there are specific scenarios where the config file method should work, please clarify:

• Which Claude Desktop versions support remote servers via config file
• Whether this requires additional setup or flags
• Platform-specific differences (if any)

However, based on current Claude Desktop behavior (tested on version 1.0.2339 from 2025-12-16), the Settings UI is the only working method.

Technical Environment Tested

• Claude Desktop Version: 1.0.2339 (1782e2) - Released 2025-12-16
• Operating System: macOS (Darwin 24.6.0)
• Node.js Version: v22.21.1 (upgraded from v21.5.0)
• npm Version: 10.9.4
• mcp-remote Package: v0.1.37

Additional Notes

• Remote MCP servers require Claude Pro, Max, Team, or Enterprise plans
• The mcp-remote package is designed as a temporary bridge solution for clients that don't yet support remote servers natively
• Claude Desktop's native remote server support through Settings > Connectors is the preferred method

References

1. Building Custom Connectors via Remote MCP Servers - Claude Help
2. Getting Started with Custom Connectors Using Remote MCP - Claude Help
3. mcp-remote npm package

---

Suggested Quick Fix

Update the "Getting Started" documentation to replace the config file instructions with:

### Connecting to Claude Desktop

1. Open Claude Desktop and ensure you have a Pro, Max, Team, or Enterprise plan
2. Navigate to **Settings > Connectors**
3. Click **Add Connector** or similar option
4. Enter the Webflow MCP server URL: `https://mcp.webflow.com/sse`
5. Complete the OAuth authorization flow when prompted
6. The Webflow connector should now appear in your available tools

**Note:** Remote MCP servers cannot be configured via the `claude_desktop_config.json` file.
That configuration method is only for local (stdio-based) MCP servers.

---

Thank you for providing this integration! Looking forward to the documentation update so other users can connect successfully.