mcp.json 完整官方详解一、基础概念1. 什么是 mcp.jsonMCP Model Context Protocol模型上下文协议是 Anthropic 推出、全行业通用的 AI 工具互通标准允许 Claude、Cursor、VS Code Copilot、JetBrains AI 等客户端连接外部工具服务文件读写、数据库、Git、网页搜索、API 调用等MCP 中...。mcp.json是MCP 客户端的核心配置文件JSON 格式用来定义一组 MCP 服务的启动 / 连接参数让 AI 自动加载外部工具能力。2. 两大场景区分容易混淆客户端配置 mcp.json99% 用户使用场景放在 AI 编辑器 / 客户端目录定义要连接哪些本地 / 远程 MCP 服务本文重点讲解。服务端发现文件 /.well-known/mcp.json部署在网站根目录用于 AI 自动发现公开 MCP 服务端点仅服务开发者使用文末简要说明。二、主流客户端配置文件路径客户端 mcp.json不同工具存储位置不同分全局配置所有项目生效、项目局部配置仅当前仓库生效优先级局部 全局CSDN博...。表格客户端全局配置路径项目局部路径Claude 桌面macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json无仅全局Cursor~/.cursor/mcp.json项目根目录.cursor/mcp.jsonVS Code Copilot用户全局~/.vscode/mcp.json项目.vscode/mcp.json.vscode/mcp.jsonJetBrains IDEs~/.config/JetBrains/IDE/ai/mcp.json项目内.idea/mcp.json1MCP AgentmacOS/Linux:~/.config/1mcp/mcp.jsonWindows:%APPDATA%\1mcp\mcp.json无三、完整顶层结构标准 schemajson{ // 全局默认配置所有服务共享单个服务字段会覆盖此处 serverDefaults: { timeout: 30000, env: {}, cwd: ${workspaceFolder} }, // 核心所有MCP服务定义key为服务唯一别名 mcpServers: { 服务别名1: { /* 服务配置 */ }, 服务别名2: { /* 服务配置 */ } }, // 可选敏感变量池统一管理密钥避免硬编码 inputs: [ { id: BRAVE_KEY, label: Brave搜索API密钥, type: password } ] }四、全字段详细说明通用顶层字段serverDefaults可选所有 MCP 服务的公共默认参数每个服务内部相同字段会覆盖默认值。支持timeout、env、cwd、disabled、alwaysLoad。mcpServers必填核心对象键为自定义服务名称英文不能重复值为单个服务完整配置。inputs可选VS Code 独有敏感凭证管理定义密码类变量配置中用${inputs.变量id}引用不会明文存入文件。单个服务配置通用字段分传输类型type区分通信模式不同 type 必填字段不同type 传输类型枚举表格type通信方式使用场景必写字段stdio最常用标准输入输出子进程本地 Node/Python/Npx 服务command、argssseServer-Sent Events 长轮询远程单向 MCP 服务url、headersstreamableHttp流式双向 HTTP现代远程 MCP 服务官方推荐url、headerswsWebSocket实时双向远程服务url1. stdio 本地进程专用字段90% 配置使用jsonfilesystem: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, ${workspaceFolder}], cwd: ${workspaceFolder}, env: { LOG_LEVEL: info, API_TOKEN: ${MY_GLOBAL_TOKEN} }, timeout: 60000, disabled: false, alwaysLoad: true, description: 本地文件读写工具访问项目目录 }逐字段解释type: 固定stdio声明本地子进程通信command必填启动程序npx/node/python/uvx/ 二进制绝对路径args必填数组传给 command 的参数路径支持变量替换cwd可选进程工作目录默认当前目录内置变量${workspaceFolder} 项目根目录env可选对象进程环境变量支持环境变量占位${VAR_NAME}禁止明文密钥timeout可选单位毫秒单次工具调用超时默认 3000030 秒disabled布尔默认 falsetrue 临时禁用该服务客户端不会启动alwaysLoad布尔默认 falsetrue 启动客户端时预加载全部工具false 按需延迟加载description可选服务备注客户端 UI 展示说明2. SSE /streamableHttp/ws 远程服务专用字段jsonremote-github-mcp: { type: streamableHttp, url: https://api.example.com/mcp/v1, headers: { Authorization: Bearer ${GITHUB_TOKEN}, Accept: application/json }, timeout: 120000, disabled: false }type:sse/streamableHttp/wsurl必填远程 MCP 服务完整地址headers可选HTTP 请求头用于鉴权、自定义参数timeout远程调用建议设 60000ms 以上无command/args/cwd远程不需要本地进程内置变量替换规则所有字段通用配置中可使用占位符自动解析无需硬编码路径 / 密钥${workspaceFolder}当前项目根目录编辑器专用${HOME}/${USERPROFILE}用户主目录${环境变量名}读取系统环境变量例${OPENAI_API_KEY}${inputs.xxx}读取顶层 inputs 中定义的敏感变量VS Code五、完整实战示例示例 1Claude 全局多服务配置stdio 本地服务文件claude_desktop_config.json等同于标准 mcp.json 格式json{ serverDefaults: { timeout: 40000 }, mcpServers: { local-fs: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/xxx/Desktop, /Users/xxx/code], env: {}, description: 本地文件读写服务 }, github-tool: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ${GH_TOKEN} }, description: GitHub 仓库操作工具 }, brave-search: { type: stdio, command: npx, args: [-y, smithery/cli, run, smithery-ai/brave-search], env: { BRAVE_API_KEY: ${BRAVE_KEY} }, timeout: 60000 } } }示例 2Cursor 项目局部配置混合本地 远程服务文件项目根目录.cursor/mcp.jsonjson{ serverDefaults: { cwd: ${workspaceFolder}, timeout: 30000 }, mcpServers: { db-sqlite: { type: stdio, command: uvx, args: [mcp-sqlite, ./data/db.sqlite3] }, remote-ai-api: { type: streamableHttp, url: https://mcp-api.example.com/stream, headers: { Authorization: Bearer ${MCP_SERVICE_TOKEN} } } } }六、安全规范必看禁止明文密钥API Key、Token 一律用${系统环境变量}占位不要写死在 JSON 内项目配置加入 .gitignore.cursor/mcp.json、.vscode/mcp.json不要提交代码仓库避免密钥泄露仅连接可信服务第三方 npx MCP 包存在执行风险不要运行来源不明的服务最小权限原则文件服务仅开放项目目录不要配置/根目录。七、补充服务端 /.well-known/mcp.json网站 MCP 发现文件部署在网站https://域名/.well-known/mcp.json用于 AI 客户端自动发现公开 MCP 服务结构完全不同json{ name: 企业业务MCP服务, description: 提供订单查询、客户管理工具, transport: streamableHttp, endpoint: https://api.xxx.com/mcp/stream, version: 1.0.0, capabilities: [tools, resources] }八、常见报错排查服务启动失败 command not foundcommand 使用绝对路径或全局安装依赖npm install -g xxx环境变量不生效占位符大小写与系统变量完全一致重启客户端重载配置工具调用超时增大timeout数值远程建议 60000ms 以上JSON 解析错误不能有注释、不能尾随逗号使用 JSON 校验工具格式化
