跳到主要内容

不写代码的消费 — 宿主、mcp.json 与排障

这一章讲三件事: 不写一行代码,怎么把一台 MCP 服务器「装」进你天天用的工具里; 装好之后,怎么管它、怎么指挥它干活; 以及出问题(一定会有)时,去哪里看、看什么。 这一章是全书离普通用户最近的一章——前面六章造东西,这一章用东西。

1. 顶层全景:宿主 = 客户端 + 模型 + 配置文件​

宿主(host)是本书给 VS Code、Claude Desktop 这类软件起的统称: 它们把 MCP 客户端、一个大语言模型、一套配置体系打包在一起, 你只管装服务器、提需求,剩下的它们办1。 一个宿主干三件事1:

  ① 按配置连上各 MCP 服务器(STDIO / SSE / Streamable HTTP 都行)
  ② 提供界面:聊天框你来说,工具结果它展示
  ③ 用配置文件记住:装了哪些服务器、各怎么启动、密钥是什么

  图说:第 06 章那个「listTools → 翻译 → 问模型 → 执行」的四步循环,
  宿主在内部替你跑——你看到的是聊天框,底下就是那四步。

本章主走查分两段:把 Playwright(一个浏览器自动化的 MCP 服务器)装进 VS Code, 用一句话让它去查「从帕丁顿到希思罗怎么坐地铁」; 然后打开 Output 面板,逐行读一次真实的握手日志。

2. mcp.json:安装 = 加一条记录​

「安装一台 MCP 服务器」在宿主里的全部含义,是往一个叫 mcp.json 的文件里 加一条记录——这个文件就是服务器清单(manifest)2。它只有两个顶级属性3:

servers:服务器条目。 三种传输,三种长相4:

{
  "servers": {
 "docs": { "type": "http", "url": "https://learn.microsoft.com/api/mcp" },  // Streamable HTTP
 "legacy": { "type": "sse",  "url": "http://localhost:8000/sse" },          // SSE
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }     // STDIO:怎么启动它
  }
}

认法一句话:远程的给 url,本地的给 command + args—— 本地服务器要由宿主负责启动(第 02 章的 spawn),所以得告诉它启动命令4。

inputs:密钥的安身之处。 服务器若要 API 密钥,直接写进这个文件太危险—— 它会进版本库(存代码和改动历史的仓库,比如 git 仓库—— 进去的东西会随代码一起被克隆、传播)、被截图、被分享。inputs 的解法是把密钥变成「启动时弹窗问一次」5:

{
  "inputs": [{
    "id": "my_api_key", "type": "promptString",
    "description": "The API key that my MCP server needs", "password": true
  }],
  "servers": {
 "my_mcp_server": { "type": "http", "url": "http://localhost:8000/mcp",
                    "headers": { "Authorization": "Bearer ${input:my_api_key}" } }
  }
}

password: true 让弹窗输入变成星号;${input:my_api_key} 是占位符, 运行时宿主拿你输的值替换,密钥从头到尾不落在这个文件里5。

装在哪还有讲究:写在项目的 .vscode/mcp.json 里只对本项目生效; 用命令面板(命令面板就是 VS Code 里按快捷键弹出的「输命令办事」的框) 选 Global 则写进用户级配置,开别的项目也在6。 作者的经验法则:常用的全局,临时的项目级6。

3. 主走查一:一句话,让浏览器自己去查地铁​

跟着书里的 Playwright 例子走一遍「装 → 用」全程7。

第 ① 步,装。 在 mcp.json 里加上面那条 playwright 记录 (VS Code 也提供图形界面和官方审核过的服务器列表可以点选安装7)。 这条记录的意思是:STDIO 服务器,用 npx @playwright/mcp@latest 启动。

第 ② 步,启动。 服务器条目上点 Start(或齿轮图标管理), 宿主 spawn 它、走握手、拿到工具清单——从此 VS Code 的聊天「知道」有浏览器可用8。

第 ③ 步,用。 在 GitHub Copilot 聊天里选 agent 模式—— agent 模式就是「允许它自己调用工具完成任务」的模式, 区别于只动嘴的问答模式——然后输入7:

Navigate to https://tfl.gov.uk/. I want to go from Paddington to Heathrow,
show me how to get there by underground, important use playwright tool

接着你会看到:聊天里弹出一个工具调用卡片,问你是否批准; 批准后,一个真浏览器被驱动起来,打开伦敦交通局网站、找输入框、填起点终点—— 一连串工具调用自动接力。作者的小技巧也实在:模型有时「不愿意」用工具, 在提示词里点名(如「important use playwright tool」,或用 # 前缀直接指定工具, 如 #add 2 and 7)能大幅提高命中率9。

第 ④ 步,收成。 查完路线后,还能让它把刚才的操作生成 Playwright 测试代码—— 作者说这才是这个服务器「真正的价值所在」:操作一次,测试留下7。

4. 管工具:勾选、点名、批准​

服务器一多,工具会多到模型犯晕(模型一次能接受的工具有上限)。 VS Code 给了三层管理9:

手段干什么什么时候用
勾选/取消勾选聊天框工具图标里,决定哪些工具对本轮对话可见工具太多、或怕它调错
#工具名提示词里直接点名必须命中某个工具时
virtualTools 设置让编辑器先按提示词筛一遍工具再提交工具数量超模型上限时

还有一道安全闸:批准。 模型想调工具时,宿主会把「它要用什么工具、 参数是什么」摆给你看,你可以只许这一次、本工作区都许、或总是允许; 手滑许错了,有 Chat: Reset Tool Confirmations 一键收回10。 作者建议:默认每次批准——批准界面同时是你检查「模型把参数解析对了没有」的机会10。

5. 主走查二:Output 面板里的一次真实握手​

服务器装不上、工具不出现时,新手第一反应是「重启试试」。 作者给了更好的地方:Output(输出)面板——VS Code 把它和每台服务器的所有往来 都记在这里,包括每一次启动、每一条 JSON-RPC 消息11。 书里贴出了一次真实记录,我们逐行读(这是全书最珍贵的一段「协议实况转播」)12:

  [editor -> server] {"jsonrpc":"2.0","id":1,"method":"initialize",
    "params":{"protocolVersion":"2025-06-18",
              "capabilities":{"roots":{"listChanged":true},"sampling":{},"elicitation":{}},
              "clientInfo":{"name":"Visual Studio Code - Insiders","version":"1.103.0-insider"}}}
      ↑ 第 ② 章的握手第 ① 步,活生生在这里。注意三处:
        协议版本是 2025-06-18(比第 02 章例子的 2024-11-05 新);
        宿主自报家门;它声明会 roots、sampling、elicitation 三样本领

  [server stderr] Debugger listening on ws://127.0.0.1:9230/…
  [info] Waiting for server to respond to `initialize` request...
  [warning] Failed to parse message: "Starting MCP server...\n"
      ↑ 全章最有价值的一行:服务器往 stdout 打印了一句问候语
        console.log("Starting MCP server...")——宿主按 JSON-RPC 解析,直接失败。
        STDIO 传输里,stdout 的每一个字节都必须是协议消息

  [server -> editor] {"result":{"protocolVersion":"2025-06-18",
    "capabilities":{"tools":{"listChanged":true}},
    "serverInfo":{"name":"demo-server","version":"1.0.0"}},"jsonrpc":"2.0","id":1}
      ↑ 握手第 ② 步:服务器回能力清单——它只会 tools

  [editor -> server] {"method":"notifications/initialized","jsonrpc":"2.0"}
  [editor -> server] {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
  [server -> editor] {"result":{"tools":[{"name":"add","title":"Addition Tool",…}]}…}
  [info] Discovered 1 tools
      ↑ 第 ③ 步通知、列工具、发现 1 个工具——第 02 章的流程一步不缺

这段日志同时是排障地图:握手卡住看 initialize 有没有回应; 工具不见看 Discovered N tools;Failed to parse 就是服务器把 stdout 当日志用了—— 修正是把日志改打 console.error(stderr 不走协议管道)12。

想再进一步,还能断点调试服务器:mcp.json 条目里加 "dev": { "watch": "build/**/*.js", "debug": { "type": "node" } }, 宿主就会以调试模式启动服务器,你在代码里下的断点会被命中13。

6. 消费侧的安全:四条底线​

这一章的安全建议针对的是「用别人服务器」的场景,和写服务器的安全(第 10 章)互补14:

  1. 密钥进 inputs,不进配置明文(第 2 节);
  2. 默认每次批准工具调用,别开「总是允许」;
  3. 限制服务器的手长:比如文件系统类服务器,只给它一个无所谓的目录;
  4. 只用可信来源:VS Code 里 @mcp 或 Browse MCP Servers 能看到官方审核过的 服务器注册表(registry);作者的建议是看作者是谁—— 「Stripe 出的 Stripe 服务器」这种对得上号的才算 reputable( reputable = 来历可信), 即便如此也要留意安全新闻,失守的事一直在发生14。

作者还给了三个自用推荐:GitHub 官方服务器(管 issue、PR)、 Playwright(操作浏览器 + 生成测试)、Microsoft Learn(在编辑器里查官方文档)15。

7. 作者的判断与证据​

有证据的:

  • mcp.json 两种属性、三种传输的条目形态、inputs 用法、本地/全局两级的位置, 都有配置实例23456;
  • Playwright 走查、批准流程、Output 日志全文,书里有图或原文71012;
  • 日志里宿主声明 roots/sampling/elicitation 三样本领、协议版本 2025-06-18, 白纸黑字12。

作者的判断:

  • 「装服务器首选编辑器内置体验,而不是网页版注册表」——个人偏好14;
  • 三个推荐服务器是作者个人工作流(他日常干活的那套流程与工具组合)的选择,他供职于微软 (三个里两个是微软系产品,详见总纲「这是谁在什么时候写的」)15。

判断(我们的,不是书里的): 这一章最该带走的不是任何一个界面操作(界面半年就变), 而是那张排障地图:Output 面板 → 握手三步 → Discovered N tools。 界面会改,协议不会——看得懂这段日志,任何宿主的任何问题你都查得了。 如果错,会错在: 如果你不用 VS Code 系宿主(比如 Claude Desktop), 面板位置和配置文件路径不同,但日志内容与排障思路原样适用—— Claude Desktop 也有自己的 MCP 日志文件(补充,不在书里,来自通用知识)。

8. 边界与局限​

  • 这一章几乎全是 VS Code(Insiders 版)的界面,界面细节过时极快—— 作者自己也提醒「这是一个变动中的领域」16;Claude Desktop 只给了一段简介和下载链接;
  • 「官方审核的注册表」在书出版时刚上线,覆盖有限;今天的官方注册表生态, 我们书架上有专门拆解17;
  • STDIO 服务器由宿主以你的权限启动——它能做的事 = 你能做的事。 书里只说了「限制目录」,没展开沙箱化(容器隔离)的方案,第 11 章生产章会再碰到;
  • # 点名、virtualTools 这些是 VS Code/Copilot 的私有功能,不是 MCP 协议的一部分。

9. 可带走的​

  1. 宿主 = 客户端 + 模型 + 配置;「安装」= 往 mcp.json 的 servers 加一条;
  2. 条目认法:远程 url(http/sse),本地 command + args;
  3. 密钥走 inputs(promptString + password),占位符 ${input:名字} 引用;
  4. 干活用 agent 模式;模型不肯用工具就 # 点名;
  5. 默认每次批准;批准卡片同时是参数审查窗口;
  6. 排障三步:Output 面板 → 看握手 → 看 Discovered N tools; Failed to parse = 服务器污染了 stdout,日志请走 console.error;
  7. 工具太多:勾选、点名、virtualTools 三层;
  8. 消费侧四底线:inputs、每次批准、限目录、只装可信来源。

10. 原文地图​

主题原书章原文位置
宿主干三件事Consuming Servers Using an IDEtext/10-fm-consuming-servers-using-an-ide.txt:81(搜「built-in MCP client」)
VS Code 功能清单同上text/10-fm-consuming-servers-using-an-ide.txt:25(搜「Installing servers」)
mcp.json 是清单同上text/10-fm-consuming-servers-using-an-ide.txt:183(搜「central concept」)
inputs 密钥同上text/10-fm-consuming-servers-using-an-ide.txt:263(搜「placeholders for sensitive information」)
三种传输条目同上text/10-fm-consuming-servers-using-an-ide.txt:308(搜「servers」)
Playwright 走查同上text/10-fm-consuming-servers-using-an-ide.txt:595(搜「Paddington to Heathrow」)
本地与全局同上text/10-fm-consuming-servers-using-an-ide.txt:625(搜「Local and global install」)
调试配置同上text/10-fm-consuming-servers-using-an-ide.txt:145(搜「dev」)
Output 日志同上text/10-fm-consuming-servers-using-an-ide.txt:853(搜「Connection state: Starting」)· :861(搜「Failed to parse message」)
工具管理同上text/10-fm-consuming-servers-using-an-ide.txt:964(搜「#add 2 and 7」)· :972(搜「virtualTools」)
批准与收回同上text/10-fm-consuming-servers-using-an-ide.txt:982(搜「Handle tool approval」)· :1018(搜「Reset Tool Confirmations」)
消费侧安全同上text/10-fm-consuming-servers-using-an-ide.txt:1058(搜「Keep secrets out of configuration」)· :1136(搜「registry of vetted MCP servers」)
推荐服务器同上text/10-fm-consuming-servers-using-an-ide.txt:1196(搜「github/github-mcp-server」)

Footnotes​

  1. 出处:「Consuming Servers Using an IDE」第 75-91 段(text/10-fm-consuming-servers-using-an-ide.txt:81,搜「built-in MCP client」)。 ↩ ↩2

  2. 出处:「Consuming Servers Using an IDE」第 183-195 段(text/10-fm-consuming-servers-using-an-ide.txt:193,搜「manifest file」)。 ↩ ↩2

  3. 出处:「Consuming Servers Using an IDE」第 251-257 段(text/10-fm-consuming-servers-using-an-ide.txt:257,搜「two primary attributes」)。 ↩ ↩2

  4. 出处:「Consuming Servers Using an IDE」第 308-394 段(text/10-fm-consuming-servers-using-an-ide.txt:366,搜「playwright」;:392,搜「these servers live remotely」)。 ↩ ↩2 ↩3

  5. 出处:「Consuming Servers Using an IDE」第 257-306 段(text/10-fm-consuming-servers-using-an-ide.txt:275,搜「promptString」;:302,搜「secrets stay out of」)。 ↩ ↩2 ↩3

  6. 出处:「Consuming Servers Using an IDE」第 625-697 段(text/10-fm-consuming-servers-using-an-ide.txt:635,搜「workspace only」;:691,搜「rule of thumb」)。 ↩ ↩2 ↩3

  7. 出处:「Consuming Servers Using an IDE」第 396-623 段(text/10-fm-consuming-servers-using-an-ide.txt:435,搜「@playwright/mcp@latest」;:595,搜「Paddington to Heathrow」;:621,搜「generate the Playwright tests」)。 ↩ ↩2 ↩3 ↩4 ↩5

  8. 出处:「Consuming Servers Using an IDE」第 539-585 段(text/10-fm-consuming-servers-using-an-ide.txt:571,搜「cog wheel」)。 ↩

  9. 出处:「Consuming Servers Using an IDE」第 597-603 段(text/10-fm-consuming-servers-using-an-ide.txt:597,搜「a bit unwilling to use a tool」)与第 948-980 段(text/10-fm-consuming-servers-using-an-ide.txt:964,搜「#add 2 and 7」;:972,搜「virtualTools」)。 ↩ ↩2

  10. 出处:「Consuming Servers Using an IDE」第 982-1022 段(text/10-fm-consuming-servers-using-an-ide.txt:990,搜「always allow」;:1018,搜「Reset Tool Confirmations」)。 ↩ ↩2 ↩3

  11. 出处:「Consuming Servers Using an IDE」第 829-845 段(text/10-fm-consuming-servers-using-an-ide.txt:845,搜「every interaction between VS Code and your server」)。 ↩

  12. 出处:「Consuming Servers Using an IDE」第 853-924 段(text/10-fm-consuming-servers-using-an-ide.txt:855,搜「protocolVersion":"2025-06-18」;:861,搜「Failed to parse message」;:866,搜「Discovered 1 tools」)。 ↩ ↩2 ↩3 ↩4

  13. 出处:「Consuming Servers Using an IDE」第 713-778 段(text/10-fm-consuming-servers-using-an-ide.txt:730,搜「"dev": {」)。 ↩

  14. 出处:「Consuming Servers Using an IDE」第 1050-1162 段(text/10-fm-consuming-servers-using-an-ide.txt:1120,搜「disallow continuous access」;:1136,搜「registry of vetted MCP servers」;:1160,搜「Stripe」)。 ↩ ↩2 ↩3

  15. 出处:「Consuming Servers Using an IDE」第 1184-1236 段(text/10-fm-consuming-servers-using-an-ide.txt:1196,搜「github/github-mcp-server」)。 ↩ ↩2

  16. 出处:「Consuming Servers Using an IDE」第 1024-1048 段(text/10-fm-consuming-servers-using-an-ide.txt:1046,搜「changing area」)。 ↩

  17. 补充(不在书里,依据我们的 protocol 书架):MCP 官方注册表(registry)已有专门拆解。 依据: shelf=ai-protocol-reference/mcp-registry#index.md 事实=该源拆解 MCP 官方服务器注册表。 ↩