使用指南·MCP

MCP 实战教程：从安装到看见效果（完整实例）

用「文件系统 MCP」走完一遍：在 AgentHub 复制配置 → Cursor 接入 → 对话里调用工具 → 看到真实读文件/列目录结果。任意 MCP 详情页都可按同一流程操作。

你将得到什么效果

做完本教程，你应该能亲眼看到这三件事（缺一则说明没接通）：

设置里已连接：Cursor → Settings → MCP，该 Server 显示绿色 Connected（或 Tools 数量 > 0）
对话里出现工具调用：如 list_directory / read_file
回复是真实本机数据：文件名或内容来自你磁盘，而不是模型瞎编的路径

本例以 文件系统 MCP 演示；打开任意 MCP 详情页，把「复制配置」换成该页的 Cursor Tab 即可，步骤通用。

实例目标与准备

实例目标

让 Cursor Agent 能列出并阅读你指定目录里的文件，例如：

问：「列出 ~/Documents/demo-mcp 下有哪些文件？」
再问：「把其中 README.md 的前 30 行读给我」

你需要

已安装 Cursor（建议最新稳定版）
本机已装 Node.js（终端执行 node -v 有版本号即可；多数 MCP 用 npx 启动）
一个练习目录（不要一上来挂整盘根目录）

mkdir -p ~/Documents/demo-mcp
echo "# MCP Demo" > ~/Documents/demo-mcp/README.md
echo "hello from mcp" > ~/Documents/demo-mcp/notes.txt

在 AgentHub 找 MCP

打开 /mcp，搜索 filesystem 或「文件系统」，进入详情页。下文以带路径参数的典型 filesystem Server 为例；字段名以详情页生成的 JSON 为准。

第一步：从 AgentHub 复制 Cursor 配置

打开目标 MCP 详情页（本例：filesystem）
找到「快速安装 / Install」区域，选 Cursor Tab
点击复制

得到类似结构（示意，以页面为准）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents/demo-mcp"
      ]
    }
  }
}

读懂这段配置（字段对照）

mcpServers 配置字段说明：顶层键、服务器名、command、args、env

无论详情页是 filesystem 还是上图里的 sbuilder-mcp，结构都一样：

字段	含义
`mcpServers`	固定顶层键
服务器名（如 `filesystem`）	命名空间，Settings 里显示的名字
`command`	用什么命令启动它（常见 `npx`）
`args`	参数；`-y` 免确认，后面通常是包名或路径
`env`	密钥等环境变量，只传给这个进程

关键点

args 最后一段若是「允许访问的目录」——务必改成你刚创建的 demo-mcp 绝对路径
macOS / Linux 用 /Users/... 或 /home/...；Windows 按该 MCP 文档写路径
若详情页有 env 占位符（API_KEY 等），先填真实值再保存，否则 Server 起不来

第二步：写入 mcp.json 并重载

项目级（推荐练习）

在你正在打开的项目根目录创建：

mkdir -p .cursor

新建或编辑 .cursor/mcp.json，把上一步的 mcpServers 合并进去。若已有其他 Server，只追加新 key，不要整文件覆盖。

完整最小示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents/demo-mcp"
      ]
    }
  }
}

然后按顺序做：

Cmd+Shift+P（Windows：Ctrl+Shift+P）→ Reload Window
打开 Cursor Settings → MCP（或 Features → MCP）
确认 filesystem 为已连接；首次 npx 可能下载几十秒：Starting → Connected

你会看到的界面效果

列表里出现名为 filesystem（或你 JSON 里的 key）的条目
展开后能看到 Tools：如 list_directory、read_file、write_file
若是红 / Error：点开日志——常见是路径写错、Node 不在 PATH、JSON 少逗号

第三步：对话调用并核对「使用效果」

打开 Agent 对话（Composer / Agent 模式，确保能使用工具），依次发送：

提示词 A｜列目录

请使用 filesystem MCP 的 list_directory（或等价工具），列出目录 /Users/你的用户名/Documents/demo-mcp 下的文件，只输出真实工具返回结果，不要猜测。

期望效果 A

出现工具调用卡片，参数路径指向 demo-mcp
结果中同时出现 README.md 与 notes.txt
若只编造文件名、且没有工具调用条 → MCP 未启用或模型没选工具，回到设置检查 Connected

提示词 B｜读文件

继续用 MCP 读取该目录下的 notes.txt 全文，原样引用内容。

期望效果 B

再次出现 read_file（或类似）工具调用
回复中出现 hello from mcp（你 echo 进去的原文）

提示词 C｜对比「没 MCP」时

关掉该 MCP，或暂时从 mcp.json 删掉后 Reload
再问同样问题：模型往往只能猜路径或说无法访问本地文件
再打开 MCP：又能读到真实内容

这就是 MCP 的价值：工具调用 + 真实结果。

第四步：换任意 MCP 复用同一套路

任意 AgentHub 上的 MCP（GitHub、Postgres、Playwright、飞书…）都按同一四步走：

详情页 → Cursor / Claude Code / VS Code Tab → 复制
合并进客户端配置，填 env / 路径 / Token
重载 → 确认 Connected + Tools
用「点名工具能力」的提示词验证

按类型怎么写验证话术

类型	验证话术	期望效果
浏览器（Playwright）	打开 https://example.com，用 MCP 截取标题，不要凭记忆	出现 navigate / snapshot 类工具调用，标题与页面一致
GitHub	用 MCP 列出我有权限的某个仓库最近 5 条 issue	需 `GITHUB_TOKEN`；返回真实 issue 标题编号
数据库	用 MCP 执行 `SELECT 1` 或列出表名	返回真实行/表；连接串错误时工具报错而不是瞎编

详情页侧栏「客户端接入与实战」也会链回本文，方便随时对照。

Claude Code / 其他客户端怎么做

Claude Code

AgentHub 详情页 → Claude Code Tab → 复制命令
终端执行，例如：

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/你/Documents/demo-mcp

开新会话，用同样的「列目录 / 读 notes.txt」提示词验证
可用 claude mcp list 查看是否已添加

VS Code / Windsurf / Cline 等

以详情页对应 Tab 生成的片段为准；验证标准不变：必须出现工具调用 + 真实数据。

更短的安装说明见：Cursor 安装 MCP、Claude Code 安装 MCP。

常见翻车与排查清单

现象	常见原因	怎么处理
JSON 无效 / 配置不加载	少逗号、写了注释、用了中文引号	用编辑器做 JSON 校验，改完再 Reload
Connected 但 Tools 为 0	包名/版本错，或 Server 启动后崩溃	打开 MCP 日志查看报错
工具调用被拒绝	未开 Auto-run / 缺工具权限	在 Cursor 里点 Approve，或开启允许运行工具
路径权限报错	访问了 `args` 允许根目录之外的路径	把目标路径放进允许目录，或改配置中的根路径（这是预期安全行为）
`npx` 拉包失败	公司代理 / 网络限制	配置 npm 镜像，或改为全局安装后再用 `node` 路径启动
安全风险	`mcp.json` 含生产密钥被提交	勿提交密钥到公开仓库；优先可信来源，详见 MCP 安全注意

做完本实例后，你可以回到任意 MCP 详情页一键复制配置，用同一套标准验收：

看见 工具调用
看见 真实结果