Figma MCP 配置时提示“Invalid MCP server URL”如何解决？

Question

Figma MCP（Model Context Protocol）配置时提示“Invalid MCP server URL”，通常源于URL格式或服务端配置不合规。常见原因包括：① URL未以 `http://` 或 `https://` 开头；② 含有空格、中文、特殊字符（如`#`、`?`）或尾部斜杠 `/`；③ 端口未显式声明（如本地服务需写为 `http://localhost:3000` 而非 `localhost:3000`）；④ MCP 服务未启动或跨域未放行（需响应头含 `Access-Control-Allow-Origin: *`）；⑤ Figma 插件 manifest.json 中 `mcpServerUrl` 字段未正确声明或未通过 Figma 官方校验（仅支持 HTTPS 生产环境，localhost 除外）。解决步骤：1）用 curl 或 Postman 验证 URL 可访问且返回有效 MCP capability 响应；2）确保 URL 符合 RFC 3986 标准；3）检查服务是否监听 0.0.0.0（而非 127.0.0.1）；4）更新 Figma Desktop 至 v132+ 并重启插件。调试建议开启浏览器 DevTools → Network 标签，观察预检请求（OPTIONS）失败原因。

Answer 1

```html

一、现象层：Figma MCP 配置报错的直观表现

在 Figma Desktop 插件设置界面输入 MCP Server URL 后，立即弹出红色提示：Invalid MCP server URL。该错误不附带堆栈或 HTTP 状态码，属客户端前置校验失败，尚未发起真实网络请求。此阶段仅验证 URL 字符串合法性，是整个调试链路的“第一道闸门”。

二、语法层：URL 结构合规性深度解析

• ✅ 必须以 http:// 或 https:// 显式协议开头（localhost:3000 或 //localhost:3000 均非法）
• ❌ 禁止尾部斜杠：http://localhost:3000/ → http://localhost:3000
• ❌ 禁止未编码的空格、中文、#、?、[、] 等 RFC 3986 非保留字符
• ⚠️ 端口必须显式声明：即使服务监听默认端口（如 HTTP 80），也需写为 http://example.com:80

三、协议层：MCP Capability 接口契约验证

合法 URL 仅是起点。Figma 客户端会向该地址发起 GET /mcp/capabilities 请求（无认证头），要求返回符合 MCP v0.1.0 规范 的 JSON 响应，且 Content-Type: application/json。常见失败响应：

{
  "error": "Not Found",
  "status": 404
}

四、网络层：跨域与监听地址的隐蔽陷阱

问题维度	典型错误	诊断命令
跨域限制	OPTIONS 预检失败，响应头缺失 Access-Control-Allow-Origin: *	curl -I -X OPTIONS http://localhost:3000/mcp/capabilities
绑定地址	服务仅监听 127.0.0.1，Figma Desktop（基于 Electron）无法通过 localhost 访问	lsof -i :3000 | grep LISTEN（macOS）

五、工程层：Figma 插件 Manifest 与运行时约束

Figma 对 manifest.json 中 mcpServerUrl 字段施加双重校验：

1. 静态校验：构建时检查是否为绝对 URL，且协议/域名符合白名单（localhost、127.0.0.1 允许 HTTP；生产环境强制 HTTPS）
2. 动态校验：插件加载时调用 Chromium 内核的 URL 解析器，拒绝含 userinfo（user:pass@）、IPv6 字面量未方括号包裹等边缘 case

六、调试流：端到端验证路径（Mermaid 流程图）

flowchart TD
    A[输入 URL 到 Figma 设置框] --> B{格式校验}
    B -- 失败 --> C[弹出 Invalid MCP server URL]
    B -- 通过 --> D[发起 GET /mcp/capabilities]
    D --> E{HTTP 200?}
    E -- 否 --> F[Network 面板查 Status/Headers]
    E -- 是 --> G{JSON Schema 校验}
    G -- 失败 --> H[响应字段缺失/类型错误]
    G -- 通过 --> I[成功启用 MCP 功能]

七、生产就绪 checklist（高阶实践）

• ✅ 使用 http://localhost:3000 开发，https://api.your-mcp.com 上线，禁止混合协议
• ✅ 服务端启用 CORS 中间件，精确设置 Access-Control-Allow-Origin 和 Access-Control-Allow-Methods
• ✅ 在 Express/Fastify 中显式绑定 0.0.0.0:3000（Docker/K8s 场景必需）
• ✅ 通过 figma dev CLI 启动插件，并开启 --verbose 查看 MCP 初始化日志

八、版本兼容性关键点

Figma Desktop v132+ 才完整支持 MCP 协议解析逻辑。旧版本会静默忽略 mcpServerUrl 字段。验证方式：

figma --version  # 输出应为 132.x 或更高
# 或在 DevTools Console 执行：
window.figma.mcp?.isAvailable // 应返回 true

九、安全边界提醒（面向资深工程师）

MCP 服务虽可本地调试，但一旦上线 HTTPS，Figma 强制要求服务端 TLS 证书由可信 CA 签发（不接受自签名或 Let's Encrypt staging 证书）。同时，/mcp/capabilities 接口不得暴露敏感元数据（如内部服务拓扑），建议通过反向代理剥离非必要响应头。

十、终极验证脚本（Shell + jq）

将以下脚本保存为 validate-mcp.sh，一键诊断核心环节：

#!/bin/bash
URL=$1
echo "🔍 Validating MCP URL: $URL"
curl -s -o /dev/null -w "%{http_code}" "$URL/mcp/capabilities" | grep -q "200" || { echo "❌ HTTP 200 failed"; exit 1; }
curl -s "$URL/mcp/capabilities" | jq -e '.capabilities' >/dev/null 2>&1 || { echo "❌ Missing 'capabilities' field"; exit 1; }
curl -sI "$URL/mcp/capabilities" | grep -i "access-control-allow-origin" | grep -q "\*" || { echo "❌ Missing CORS header"; exit 1; }
echo "✅ All checks passed"

```