mcp.json 完整官方详解

mcp.json 完整官方详解

一、基础概念

1. 什么是 mcp.json

MCP = Model Context Protocol（模型上下文协议），是 Anthropic 推出、全行业通用的 AI 工具互通标准，允许 Claude、Cursor、VS Code Copilot、JetBrains AI 等客户端连接外部工具服务（文件读写、数据库、Git、网页搜索、API 调用等）MCP 中...。mcp.json是MCP 客户端的核心配置文件，JSON 格式，用来定义一组 MCP 服务的启动 / 连接参数，让 AI 自动加载外部工具能力。

2. 两大场景区分（容易混淆）

1. 客户端配置 mcp.json（99% 用户使用场景）放在 AI 编辑器 / 客户端目录，定义要连接哪些本地 / 远程 MCP 服务，本文重点讲解。
2. 服务端发现文件 /.well-known/mcp.json部署在网站根目录，用于 AI 自动发现公开 MCP 服务端点，仅服务开发者使用，文末简要说明。

二、主流客户端配置文件路径（客户端 mcp.json）

不同工具存储位置不同，分全局配置（所有项目生效）、项目局部配置（仅当前仓库生效），优先级：局部 > 全局CSDN博...。

表格

三、完整顶层结构（标准 schema）

json

{ // 全局默认配置，所有服务共享，单个服务字段会覆盖此处 "serverDefaults": { "timeout": 30000, "env": {}, "cwd": "${workspaceFolder}" }, // 核心：所有MCP服务定义，key为服务唯一别名 "mcpServers": { "服务别名1": { /* 服务配置 */ }, "服务别名2": { /* 服务配置 */ } }, // 可选：敏感变量池，统一管理密钥，避免硬编码 "inputs": [ { "id": "BRAVE_KEY", "label": "Brave搜索API密钥", "type": "password" } ] }

四、全字段详细说明

通用顶层字段

1. serverDefaults（可选）所有 MCP 服务的公共默认参数，每个服务内部相同字段会覆盖默认值。支持：timeout、env、cwd、disabled、alwaysLoad。
2. mcpServers（必填，核心）对象，键为自定义服务名称（英文，不能重复），值为单个服务完整配置。
3. inputs（可选，VS Code 独有）敏感凭证管理，定义密码类变量，配置中用${inputs.变量id}引用，不会明文存入文件。

单个服务配置通用字段（分传输类型）

type区分通信模式，不同 type 必填字段不同：

type 传输类型枚举

表格

1. stdio 本地进程专用字段（90% 配置使用）

json

"filesystem": { "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（可选，单位毫秒）：单次工具调用超时，默认 30000（30 秒）
• disabled（布尔，默认 false）：true = 临时禁用该服务，客户端不会启动
• alwaysLoad（布尔，默认 false）：true = 启动客户端时预加载全部工具；false = 按需延迟加载
• description（可选）：服务备注，客户端 UI 展示说明

2. SSE /streamableHttp/ws 远程服务专用字段

json

"remote-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/ws
• url（必填）：远程 MCP 服务完整地址
• headers（可选）：HTTP 请求头，用于鉴权、自定义参数
• timeout：远程调用建议设 60000ms 以上
• 无command/args/cwd（远程不需要本地进程）

内置变量替换规则（所有字段通用）

配置中可使用占位符自动解析，无需硬编码路径 / 密钥：

1. ${workspaceFolder}：当前项目根目录（编辑器专用）
2. ${HOME}/${USERPROFILE}：用户主目录
3. ${环境变量名}：读取系统环境变量，例${OPENAI_API_KEY}
4. ${inputs.xxx}：读取顶层 inputs 中定义的敏感变量（VS Code）

五、完整实战示例

示例 1：Claude 全局多服务配置（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 } } }

示例 2：Cursor 项目局部配置（混合本地 + 远程服务）

文件：项目根目录.cursor/mcp.json

json

{ "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}" } } } }

六、安全规范（必看）

1. 禁止明文密钥：API Key、Token 一律用${系统环境变量}占位，不要写死在 JSON 内；
2. 项目配置加入 .gitignore：.cursor/mcp.json、.vscode/mcp.json不要提交代码仓库，避免密钥泄露；
3. 仅连接可信服务：第三方 npx MCP 包存在执行风险，不要运行来源不明的服务；
4. 最小权限原则：文件服务仅开放项目目录，不要配置/根目录。

七、补充：服务端 /.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"] }

八、常见报错排查

1. 服务启动失败 command not found
   • command 使用绝对路径；或全局安装依赖（npm install -g xxx）
2. 环境变量不生效
   • 占位符大小写与系统变量完全一致，重启客户端重载配置
3. 工具调用超时
   • 增大timeout数值（远程建议 60000ms 以上）
4. JSON 解析错误
   • 不能有注释、不能尾随逗号，使用 JSON 校验工具格式化