VS Code客户端必须使用vscode-mcp插件（v0.8.3+），因其是唯一官方支持mcp://协议、TLS双向认证及caCertPath配置的插件；其他MCP插件如Cline不兼容私有云所需的jsonrpc-tls传输与证书校验逻辑。
VS Code 客户端必须用 vscode-mcp，不是随便一个 AI 插件都能接私有 MCP
私有云部署下，VS Code 侧唯一被官方支持、能正确解析 mcp:// 协议并处理 TLS 双向认证的插件是 vscode-mcp（v0.8.3+）。Cline、IC Coder 或 Claude Code 等插件虽支持 MCP，但它们默认走 HTTP/HTTPS 或自定义 transport，无法加载私有环境要求的客户端证书、校验服务端 CA、或识别 mcp:// scheme 触发内置 TLS 校验逻辑。
常见错误现象：
– 配置了 "transport": "jsonrpc-tls" 却报 ERR_CONNECTION_REFUSED 或 self signed certificate
– 插件日志里出现 Unknown transport type 'jsonrpc-tls'
– mcp.json 文件被忽略，服务列表为空
- 务必从 VS Code 扩展市场搜索安装
vscode-mcp，而非“MCP Client”“MCP for VS Code”等模糊名称 - 卸载所有其他声称支持 MCP 的插件（尤其是 Cline），避免 transport 冲突
- 确认插件版本 ≥ 0.8.3：在扩展详情页看“Version”字段，旧版不支持
caCertPath
私有 MCP Server 必须启用 JSON-RPC over TLS 1.3，且证书需由可信 CA 签发
开发模式下用 http://localhost:8080 能通，不代表私有云能过。生产级私有部署强制要求 jsonrpc-tls transport，且服务端必须满足：
- 监听
0.0.0.0:8080（不能只绑127.0.0.1） - 使用 TLS 1.3 协议（OpenSSL 3.0+），禁用 TLS 1.0/1.1
- 服务端证书由企业内网 CA 或 Let’s Encrypt 签发，不能是自签名证书（否则客户端拒绝连接）
- 启动命令中必须显式指定
--tls-cert和--tls-key，例如：mcp-server-jsonrpc --host 0.0.0.0 --port 8080 --tls-cert /etc/mcp/fullchain.pem --tls-key /etc/mcp/privkey.pem
容易踩的坑：
– 用 mkcert 生成的证书，VS Code 客户端不信任（即使已导入系统根证书）
– Nginx 反代 MCP 服务时未透传 TLS，导致客户端收到 HTTP 响应却期待 TLS 握手
– 服务端未开启双向认证（--tls-require-client-cert），但客户端配置了 caCertPath，连接直接中断
mcp.json 必须放在工作区根目录，且 endpoint 必须用 mcp:// scheme
VS Code 的 vscode-mcp 插件只在打开文件夹（即有工作区）时读取根目录下的 .vscode/mcp.json。全局设置或用户 settings.json 中的 mcp.client.servers 不生效。
正确配置示例（保存为 .vscode/mcp.json）：
{
"servers": [
{
"name": "prod-mcp-cluster",
"transport": "jsonrpc-tls",
"endpoint": "mcp://mcp.internal.corp:8080",
"caCertPath": "/usr/local/share/ca-certificates/corp-ca.crt"
}
]
}
关键点：
– endpoint 必须以 mcp:// 开头，这是触发插件启用 TLS 校验的开关
– caCertPath 是客户端本地路径，指向已部署的企业 CA 证书（PEM 格式）
– 路径必须绝对，不能用 ~ 或环境变量
– 如果服务跑在 Kubernetes 里，endpoint 应填 Ingress 域名（如 mcp.internal.corp），而非 ClusterIP 或 Pod IP
连通性验证不能只靠 ping 或 curl，得用标准 capabilities 请求
很多工程师用 curl https://mcp.internal.corp:8080 返回 404 就认为服务没起来——这完全错误。MCP 服务不提供 HTTP 页面，只响应 JSON-RPC 消息。
真正有效的验证方式是发送标准初始化请求，并检查 capabilities 字段：
curl -k \
--cert /path/to/client.pem \
--key /path/to/client.key \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
https://mcp.internal.corp:8080 | jq '.result.capabilities'
预期输出应为非空 JSON 对象，包含 tools、serverInfo 等字段。若返回 Unauthorized，说明证书或身份校验失败；若超时，检查防火墙、Ingress TLS 终止策略、或服务是否真在监听。
最容易被忽略的地方：
– 客户端证书（--cert）必须由同一 CA 签发，且未过期
– jq 不是必须的，但不用它就很难判断返回是否结构合法
– -k 仅用于跳过服务端证书校验，不能跳过客户端证书校验
