1. 为什么先跑 Filesystem Server 再谈 Agent Skills如果你刚开始接触 MCP直接翻协议文档或者 SDK 源码大概率会在 Host、Client、Server、Transport 这几个词之间绕晕。我自己的经验是先连一个现成的本地 Server把整条链路跑通再回头看架构图很多概念会瞬间对上号。Filesystem Server 就是最适合当起点的那个。它做的事情很朴素——让 AI 应用能读写你指定的本地目录但它把本地 MCP 服务的核心机制全暴露出来了Host 怎么读配置、command 和 args 到底在干什么、为什么本地 Server 是一个子进程、stdio 怎么把两端接起来、目录授权和逐次 Approval 有什么区别。这些搞清楚了后面用 Agent Skills 构建自己的 Server 时架构选择就不会拍脑袋。这篇的目标很明确给你一份可复制的 config.toml 和 settings.json 骨架用 TaoToken 统一 Key 打通 API 通道然后做一次本地 MCP 服务的连通性验证跑通从配置到调用的最小闭环。适合已经装好 Node.js、想动手而不是只看概念的人。2. TaoToken 前置统一 Key 与 API 通道准备本地 MCP 服务本身不一定要联网但一旦你的 Server 要调用模型能力比如让 Agent 在读写文件时做总结、分类、生成内容就需要一个稳定的 API 通道。TaoToken 在这里的角色是统一 Key 管理你不用在每台机器、每个项目里散落不同的 Key而是通过一个入口拿到 API Key再在配置里引用。先拿到 Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key复制出来。这个 Key 后面会写进环境变量不要直接硬编码在会被提交到 Git 的文件里。TaoToken 的 API 基地址是 https://taotoken.net/api 注意这个地址不带任何查询参数。模型对话、Coding Plan、控制台这些入口分别是模型对话https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意Key 只显示一次创建后立刻复制保存。如果怀疑泄露直接在控制台吊销重建不要试图“改一改继续用”。环境变量建议这样设macOS/Linux 写进~/.zshrc或~/.bashrcWindows 用系统环境变量面板export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api设完执行source ~/.zshrc再用echo $TAOTOKEN_API_KEY确认能打印出来。这一步没做对后面所有配置都会在鉴权环节失败。3. 可复制配置config.toml 与 settings.json 骨架本地 MCP 服务的配置分两层一层是 Server 本身的定义用什么命令启动、传什么参数、环境变量是什么另一层是 Host 侧的接入配置。不同 Host 用的格式不一样这里给两种最常见的。3.1 config.tomlServer 定义骨架如果你用的是支持 TOML 的 Host 或自己写的启动器可以这样组织[mcp_servers.filesystem] command npx args [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/Desktop, /Users/yourname/Downloads ] env { TAOTOKEN_API_KEY ${TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL https://taotoken.net/api } [mcp_servers.filesystem.limits] timeout_ms 30000 max_output_bytes 1048576逐项说清楚。mcp_servers是配置集合一个 Host 可以同时挂多个 Server比如再加一个github、一个weather。filesystem只是这条配置的友好名称你可以改成my-local-files它只影响 UI 展示和日志区分不影响实际执行。真正跑起来的是modelcontextprotocol/server-filesystem这个 npm 包。command npx表示 Host 会去执行 npx。npx 能下载或运行 npm 包所以本机必须有 Node.js。-y是自动确认安装提示避免 GUI Host 启动子进程时卡在交互确认上。后面两个路径参数限定 Server 允许操作的目录——只放你愿意交给 AI 访问的位置别图省事写根目录。env里把 TaoToken 的 Key 和 Base URL 传进去这样 Server 内部如果要调模型直接读环境变量就行不用在代码里写死。3.2 settings.jsonHost 侧接入片段Claude Desktop 这类 Host 用的是 JSON。macOS 路径是~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 是%APPDATA%\Claude\claude_desktop_config.json{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/Desktop, /Users/yourname/Downloads ], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }改完配置必须完全退出应用再重启不是关窗口。重启后在 Connectors 或 Manage connectors 里检查Server 有没有出现、Tool 有没有列出来、有没有连接错误。3.3 从启动到连接发生了什么Host 读到配置后链路是这样的Host 读取 mcpServers.filesystem ↓ 执行 npx -y modelcontextprotocol/server-filesystem directories ↓ OS 启动 Filesystem Server 子进程 ↓ Host 创建 MCP Client 实例 ↓ Client 通过 stdio 与子进程通信 ↓ Client 发 tools/list ↓ Host 在 UI 展示可用文件 Tool对应到架构Host 是 Claude Desktop 或其他支持 MCP 的 AI 应用MCP Client 是 Host 内部为这个 Server 创建的连接对象MCP Server 是那个子进程Transport 是 stdio外部能力是你允许目录里的文件操作。stdio 为什么适合本地 Server它用 stdin 做 Host→Server、stdout 做 Server→Host、stderr 做日志不需要开网络端口Host 负责启停进程延迟低生命周期好绑定。但有一条铁律stdio Server 不能把普通日志写到 stdout否则会污染 JSON-RPC 消息日志一律走 stderr。4. 验证请求一次本地 MCP 服务连通性检查配置写完别急着在 UI 里点来点去先用命令行确认 Server 能起来、能响应。4.1 手动启动 Server在终端直接跑npx -y modelcontextprotocol/server-filesystem /Users/yourname/Desktop如果 Node.js 和 npm 正常你会看到进程挂起等待输入这说明 Server 已经启动并在 stdio 上监听。按 CtrlC 退出。4.2 用 MCP Inspector 做协议级验证MCP Inspector 是最直接的调试工具npx modelcontextprotocol/inspector npx -y modelcontextprotocol/server-filesystem /Users/yourname/Desktop它会启动一个本地 Web 界面你在里面能看到 Server 暴露的所有 Tool比如read_file、write_file、list_directory。点开list_directory参数填/Users/yourname/Desktop执行如果返回目录列表说明 stdio 传输、Tool 发现、参数校验、结果返回整条链路都通了。4.3 在 Host 里做一次真实调用回到 Claude Desktop输入类似“列出我 Downloads 里的工作文件”这样的请求。观察几件事Host 有没有正确选中 Tool、Tool Arguments 是不是在允许路径内、写操作有没有弹 Approval、拒绝后是否停止、Result 是否正确返回。如果这一步成功你的最小闭环就跑通了配置 → 启动子进程 → stdio 连接 → Tool 发现 → 调用 → 结果返回。4.4 目录范围与 Approval 是两回事很多人会混淆这两个概念。配置里的目录参数回答的是“这个 Server 最多能在哪些目录工作”是 Server 的边界。每次 Approval 回答的是“当前这一次读取、写入、移动或删除是否允许”是 Host 的策略。允许目录不能替代逐次确认逐次确认也不能扩大 Server 的目录边界。两者叠加才是完整的安全模型。5. 本篇常见错排查5.1 Server 没有出现在 Host 里按顺序查JSON 是否合法用python -m json.tool或在线校验、配置文件位置对不对、command 是否存在、Node.js 和 npm 是否装了、目录是否存在、是否完全重启了 Host。JSON 里多一个逗号就会导致整个配置被忽略这是最高频的坑。5.2 GUI Host 找不到 npxGUI 应用的 PATH 往往和终端不一样。终端里which npxWindows 用where.exe npx拿到绝对路径然后把配置里的command改成绝对路径比如/usr/local/bin/npx。5.3 目录权限不足Server 以当前用户权限运行。检查 OS 文件权限、macOS 隐私权限、目录是否只读、文件是否被其他进程占用、Server 配置是否包含目标目录。macOS 上如果目录在“桌面/文稿/下载”里可能需要在系统设置里给终端或 Host 授予完全磁盘访问权限。5.4 Windows 环境变量没展开如果日志里%APPDATA%没有按预期传入子进程在 Server Config 的env里直接写展开后的值并确认 npm 在 GUI 环境里可用。5.5 stdio Server 把日志写到了 stdout症状是 Host 报 JSON 解析错误或者连接莫名其妙断开。检查 Server 代码或依赖确保所有日志走 stderr。第三方包如果有这个问题去它的 issue 区看看有没有已知修复版本。5.6 日志在哪看Claude Desktop 的mcp.log记录连接和 Client 层问题mcp-server-SERVERNAME.log记录对应 stdio Server 的 stderr。macOS 常见目录是~/Library/Logs/ClaudeWindows 是%APPDATA%\Claude\logs。分享日志前务必删掉 Token、API Key、Authorization Header、私人文件路径和敏感内容。6. 从连接现成 Server 到用 Agent Skills 构建自己的跑通 Filesystem Server 之后下一步自然是构建自己的 Server。官方提供的 Agent Skills 是一组给 Coding Agent 用的构建指令包包括build-mcp-server入口分析场景并选择部署和 Tool 设计、build-mcp-app添加聊天内表单、Picker、Chart 等 Rich UI、build-mcpb把本地 stdio Server 与 Runtime 打包成 .mcpb。要特别注意这些名字不是 MCP Method不是tools/list返回的 Tool也不是 Server 运行时的 Primitive。它们是给 AI Coding Agent 用的 Instruction Package只在开发阶段起作用不会成为最终 MCP Runtime 的一部分。一份 Skill 通常长这样skill-directory/ ├─ SKILL.md └─ references/ ├─ auth-patterns.md ├─ tool-design.md ├─ widget-templates.md └─ manifest-schema.mdSKILL.md告诉 Coding Agent 什么时候触发、先问哪些问题、怎么选架构、读哪些参考资料、怎么生成项目、怎么测试交付。build-mcp-server不会立刻写代码而是先做 Discovery连接什么Cloud API / Local Process / Filesystem / Hardware / Database、谁用自己 / 团队 / 所有安装者 / 公共 SaaS 用户、Action Surface 多大、需要什么交互、上游怎么认证。这些答案决定 Transport、Auth、Tool 设计和分发方式。部署路径有四条Remote Streamable HTTP 适合包装 Cloud API一次部署服务多用户MCP App 适合复杂聊天内 UIMCPB 适合必须访问用户本机的 Server把 Server 和 Runtime 打包成一个 .mcpbLocal stdio 适合原型和个人工具。决策树很简单包装云 API 优先 Remote HTTP需要复杂 UI 走 MCP App必须访问本机走 MCPB否则本地原型先 stdio。脚手架生成只是开始。后续必须改进 Tool Name 和 Description、定义 Input/Output Schema、处理 Error、加 Auth、用 MCP Inspector 测试、连真实 Client、验证 Approval、记日志和指标。别把“Agent 已经生成代码”理解成“Server 已经达到生产质量”。如果你在接入或排障过程中卡住可以直接去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 检查 Key 状态接入细节看 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先验证模型通道是否正常用 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 发一条消息试试。如果你打算长期做编码类 Agenthttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 会更合适。
