mcp.json 完整官方详解
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 校验工具格式化

相关新闻

华为OD机试 新系统真题 【小明的顺风车】

华为OD机试 新系统真题 【小明的顺风车】

小明的顺风车(C++/Go/C/Js/JAVA/Py)题解 华为OD机试新系统真题 华为OD上机考试新系统真题 7月19号 200分题型 华为OD机试新系统真题目录点击查看: 华为OD机试新系统真题题库目录|机考题库 + 算法考点详解 题目内容 小明自驾回家,为节省旅途成本,决定在网上挂出顺风车服务…

2026/11/21 7:42:44 阅读更多 →
华为OD机试 新系统真题 【酒店服务记录分析】

华为OD机试 新系统真题 【酒店服务记录分析】

酒店服务记录分析(C++/Go/C/Js/Java/Py)题解 华为OD机试 新系统真题 华为OD上机考试 新系统真题 7月19号 100分题型 华为OD机试新系统真题目录点击查看: 华为OD机试新系统真题题库目录|机考题库 + 算法考点详解 题目内容 你是某连锁酒店的数据分析师,酒店每天都会用一串编…

2026/11/21 7:42:44 阅读更多 →
支付系统的分布式事务实践——从业务需求到 Seata Saga 模式的落地路径

支付系统的分布式事务实践——从业务需求到 Seata Saga 模式的落地路径

支付系统的分布式事务实践——从业务需求到 Seata Saga 模式的落地路径 一、支付系统的分布式事务困境:一笔订单为何涉及 5 个服务 2025 年 Q3,团队接手了一个聚合支付系统的重构任务。这个系统连接了支付宝、微信支付、银联云闪付三条支付通道&#xff…

2026/11/14 5:50:14 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/20 23:27:28 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/20 23:27:28 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/20 23:27:28 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/20 21:55:32 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/20 23:27:28 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/20 22:59:12 阅读更多 →

日新闻

周新闻

月新闻