从 Filesystem Server 到 Agent Skills：连接和构建本地 MCP 服务

MCP 从入门到工程实践系列，第 5 篇，共 9 篇。
本文完成两件事：连接一个现成的本地 Server；理解开发新 Server 时如何选择构建路径。

学习 MCP 时，直接从协议或 SDK 代码开始，很容易把 Host、Client、Server 和 Transport 混在一起。

更直观的方法是先连接一个现成的 Filesystem Server。

它能帮助我们看到：

• Host 怎样读取 Server 配置；
• command 和 args 到底做什么；
• 本地 Server 为什么是一个子进程；
• MCP Client 在哪里创建；
• stdio 怎样连接两端；
• 目录授权和每次操作 Approval 有什么区别；
• Agent Skills 为什么不是 MCP Protocol Method。

一、先看 Filesystem Server 配置

典型配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

很多疑问都集中在 filesystem 这个词上：

它是一个 Python 库、MCP Method，还是操作系统的文件系统？

答案是：

这里的 filesystem 只是这条 Server 配置的友好名称；真正执行的是 @modelcontextprotocol/server-filesystem 包。

二、逐项解释配置

1. mcpServers

Host 的 MCP Server 配置集合。

一个 Host 可以同时配置：

{
  "mcpServers": {
    "filesystem": {},
    "github": {},
    "weather": {}
  }
}

每一项描述怎样连接一个 Server。

2. filesystem

这是配置 Key，可以改名：

{
  "mcpServers": {
    "my-local-files": {
      "...": "..."
    }
  }
}

它通常用于：

• UI 展示；
• 日志区分；
• 配置管理。

3. command: "npx"

Host 会执行 npx 命令。

npx 可以下载或运行 npm Package，因此本机需要 Node.js。

4. -y

自动确认 npx 的安装或执行提示，避免 GUI Host 启动子进程时卡在交互确认。

5. @modelcontextprotocol/server-filesystem

这才是真正运行的 MCP Filesystem Server Package。

它负责：

• 接收 MCP Request；
• 暴露文件相关 Tool；
• 校验路径是否在允许目录中；
• 执行读取、写入、移动等操作；
• 返回 Tool Result。

6. 目录参数

/Users/username/Desktop
/Users/username/Downloads

它们限定 Server 被配置为允许操作的目录。

只应加入你愿意交给 AI Application 访问的位置。

三、从启动到连接发生了什么

Host 读取配置后：

Host 读取 mcpServers.filesystem
        ↓
执行 npx -y @modelcontextprotocol/server-filesystem <directories>
        ↓
OS 启动 Filesystem Server 子进程
        ↓
Host 创建一个 MCP Client 实例
        ↓
Client 通过 stdio 与子进程通信
        ↓
Client tools/list
        ↓
Host 在 UI 中展示可用文件 Tool

这里可以对应 MCP 架构：

组件	具体对象
Host	Claude Desktop 或其他支持 MCP 的 AI Application
MCP Client	Host 内部为 Filesystem Server 创建的连接对象
MCP Server	server-filesystem 子进程
Transport	stdio
外部能力	本机允许目录中的文件操作

四、stdio 为什么适合本地 Server

stdio 使用：

stdin  = Host/Client → Server
stdout = Server → Host/Client
stderr = Server 日志

优点：

• 不需要开放网络端口；
• Host 可以负责启动和停止进程；
• 延迟低；
• 适合同机工具；
• Server 生命周期和连接生命周期容易绑定。

重要规则：

stdio Server 不能把普通日志写到 stdout，否则会污染 JSON-RPC 消息。

日志应该写 stderr。

五、目录范围与操作 Approval 不是一回事

配置目录：

/Users/username/Desktop

回答的是：

这个 Server 最多可以在哪些目录工作？

每次 Approval 回答的是：

当前这一次读取、写入、移动或删除是否允许？

Server Allowed Directory
        ↓
Tool Call 仍要经过 Host Policy
        ↓
必要时展示 Approval
        ↓
用户允许或拒绝

允许目录不能替代逐次确认，逐次确认也不能扩大 Server 的目录边界。

六、Claude Desktop 示例怎样配置

官方页面使用 Claude Desktop 说明本地连接，其他 MCP Host 的概念相同。

配置文件位置：

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

修改后应完全退出并重新启动应用，而不是只关闭窗口。

随后在 Connectors 或 Manage connectors 中检查：

• Server 是否出现；
• Tool 是否列出；
• 是否有连接错误。

七、可以怎样测试 Filesystem Server

官方页面给出的思路包括：

• 写一首诗并保存到 Desktop；
• 列出 Downloads 中的工作文件；
• 创建 Images 目录；
• 把 Desktop 图片移动到新目录；
• 读取某个文本文件并总结。

测试时观察：

1. Host 是否正确选择 Tool；
2. Tool Arguments 是否是允许路径；
3. 写操作是否出现 Approval；
4. 拒绝后是否停止；
5. Result 是否正确返回。

八、常见连接问题

1. Server 没有出现

依次检查：

• JSON 是否合法；
• 配置文件位置是否正确；
• command 是否存在；
• Node.js 和 npm 是否安装；
• 目录是否存在；
• 是否完全重启 Host。

2. GUI Host 找不到 npx

GUI Application 的 PATH 可能不同于 Terminal。

可以在终端查：

which npx

Windows：

where.exe npx

必要时在 command 中写绝对路径。

3. 目录权限不足

Server 以当前用户权限运行。

需要检查：

• OS File Permission；
• macOS 隐私权限；
• 目录是否只读；
• 文件是否被其他进程占用；
• Server 配置是否包含目标目录。

4. Windows 环境变量没有展开

如果日志中的 APPDATA 没有按预期传入子进程，可以在 Server Config 的 env 中传入展开后的值，并确认 npm 在 GUI 环境中可用。

九、日志在哪里看

Claude Desktop 示例中：

• mcp.log：连接和 Client 层问题；
• mcp-server-SERVERNAME.log：对应 stdio Server 的 stderr。

macOS 常见日志目录：

~/Library/Logs/Claude

Windows：

%APPDATA%\Claude\logs

分享日志前要删除：

• Token；
• API Key；
• Authorization Header；
• 私人文件路径；
• 敏感内容。

十、连接现成 Server 后，怎样构建自己的 Server

官方“Build with Agent Skills”页面提供一组给 Coding Agent 使用的构建 Skill：

Skill	作用
build-mcp-server	入口 Skill，分析场景并选择 Deployment 和 Tool Design
build-mcp-app	添加聊天内表单、Picker、Chart、Dashboard 等 Rich UI
build-mcpb	把本地 stdio Server 与 Runtime 打包为 .mcpb

这些名称不是：

• MCP Method；
• tools/list 返回的 Tool；
• Server 运行时 Primitive。

它们是给 AI Coding Agent 使用的 Instruction Package。

十一、Agent Skill 内部是什么

一份 Skill 通常包含：

skill-directory/
  ├─ SKILL.md
  └─ references/
       ├─ auth-patterns.md
       ├─ tool-design.md
       ├─ widget-templates.md
       └─ manifest-schema.md

SKILL.md 告诉 Coding Agent：

• 什么时候触发；
• 应先问哪些问题；
• 应如何选择架构；
• 应读取哪些参考资料；
• 怎样生成项目；
• 如何测试和交付。

Skill 帮助 Agent 写代码，但不会成为最终 MCP Runtime 的一部分。

十二、build-mcp-server 会先问什么

它通常不会立刻开始写代码，而是先做 Discovery：

1. 连接什么

• Cloud API；
• Local Process；
• Filesystem；
• Hardware；
• Database。

2. 谁使用

• 只有自己；
• 团队内部；
• 面向所有安装者；
• 公共 SaaS 用户。

3. Action Surface 多大

• 只有几个明确操作；
• 包装一个大型 API；
• 需要 Progressive Discovery；
• 是否包含副作用。

4. 需要什么交互

• 纯文本 Result；
• Elicitation Form；
• Searchable Picker；
• Chart；
• Live Dashboard。

5. 上游怎样认证

• API Key；
• OAuth 2.0；
• 用户本机 Session；
• 无认证。

这些答案决定 Server 的 Transport、Auth、Tool 设计和分发方式。

十三、四种部署路径怎样选

路径 1：Remote Streamable HTTP

适合包装 Cloud API。

优势：

• 一次部署服务多个用户；
• 用户不必安装 Runtime；
• OAuth Redirect 和 Token Storage 更自然；
• Server 可统一更新。

官方 Reference Skill 提到 Cloudflare Workers 和 Express/FastMCP Scaffold。

路径 2：MCP App

适合普通文本或扁平 Elicitation Form 无法表达的 UI：

• 搜索选择器；
• 图表；
• 实时 Dashboard；
• 复杂预览；
• 多区域交互。

build-mcp-app 用于这类场景。

路径 3：MCPB

适合必须访问用户本机的 Server：

• 本地文件；
• 桌面应用；
• localhost 服务；
• 本机 Runtime；
• 硬件。

MCP Bundle 把 Server 与 Node/Python 等 Runtime 打包为一个 .mcpb Archive，让用户无需单独配置开发环境。

路径 4：Local stdio

适合：

• 原型；
• 个人工具；
• 本地开发；
• 尚未准备分发的 Server。

准备面向更多用户分发时，可以再升级到 MCPB。

十四、选择路径的简单决策树

是否包装云 API？
  ├─ 是 → 优先 Remote Streamable HTTP
  └─ 否
      ↓
是否需要复杂聊天内 UI？
  ├─ 是 → MCP App
  └─ 否
      ↓
是否必须访问用户本机？
  ├─ 是 → MCPB
  └─ 否 → 本地原型可先 stdio

真实项目可以组合，例如：

• Remote Server + MCP App；
• Local Server 原型 → MCPB 分发；
• Remote API + OAuth；
• stdio Server + 简单 Elicitation。

十五、脚手架之后还要做什么

Agent Skill 生成项目只是开始。

后续必须：

1. 改进 Tool Name 和 Description；
2. 定义 Input/Output Schema；
3. 处理 Error；
4. 加入 Authentication 和 Authorization；
5. 使用 MCP Inspector 测试；
6. 连接真实 Client；
7. 验证 Approval；
8. 记录日志和指标；
9. 根据需要发布到 MCP Registry。

不要把“Agent 已经生成代码”理解为“Server 已经达到生产质量”。

十六、常见误区

误区 1：filesystem 是 MCP 内置 Method

不是。它只是配置名称。

误区 2：npx 就是 MCP Client

不是。npx 只是启动 npm Package；MCP Client 在 Host 内部。

误区 3：目录参数等于每次操作都已授权

不是。目录是 Server 范围，Host 仍可逐次要求 Approval。

误区 4：stdio Server 可以随便 print

普通 stdout 文本会污染协议，应写 stderr。

误区 5：build-mcp-app 是模型可调用的 MCP Tool

不是。它是开发阶段给 Coding Agent 使用的 Skill。

误区 6：所有 Server 都应该使用 MCPB

MCPB 面向本地分发；Cloud API 通常更适合 Remote HTTP。

误区 7：脚手架生成后不需要测试

必须用 Inspector、真实 Client 和安全测试验证。

总结

通过 Filesystem Server，可以看到本地 MCP 的完整启动链：

Host Config
  ↓
command + args
  ↓
启动本地 Server 子进程
  ↓
创建 MCP Client
  ↓
stdio 连接
  ↓
发现和调用 Tool

通过 Agent Skills，可以理解构建新 Server 前的架构选择：

build-mcp-server
  ├─ Remote Streamable HTTP
  ├─ MCP App
  ├─ MCPB
  └─ Local stdio

下一篇开始写代码：使用 Python、MCPServer 和 httpx2 构建 Weather Server，并逐行解释 HTTP Header、async/await、JSON、NWS 两次 API 调用和 Tool Schema。

如果本文帮你理解了 Filesystem Server 配置和 Agent Skills，欢迎点赞、收藏。下一篇将进入完整 Python Server 实战。

参考资料

• https://modelcontextprotocol.io/docs/2026-07-28/develop/connect-local-servers
• https://modelcontextprotocol.io/docs/2026-07-28/develop/build-with-agent-skills
• https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture
• https://modelcontextprotocol.io/docs/2026-07-28/tools/debugging