# MCP 配置指南：在 NearWork 里接入任意 MCP 服务器

> NearWork 支持 stdio 与 HTTP 两种 MCP 传输。本文给出 mcp.json 的完整写法、用户级与项目级配置的优先级、常用插件推荐与连不上的排查顺序。

MCP（Model Context Protocol）是让 AI 调用外部工具的开放协议：把 Notion、GitHub、数据库、浏览器这些能力挂到 NearWork 身上，AI 就能直接读写它们。NearWork 内置 MCP 客户端，支持 **stdio** 与 **HTTP** 两种传输，配置一次即可长期复用。

## 三种接入方式，按熟练度选

| 方式 | 适合 | 做法 |
|---|---|---|
| 插件市场安装 | 绝大多数人 | 侧边栏「插件 → 插件市场」，搜索后一键安装，需要 Token 的会弹窗让你填 |
| 手动添加 | 市场里没有的服务 | 侧边栏「插件 → 手动添加」，或直接编辑 `mcp.json` |
| 让 AI 帮你加 | 已经有配置文件 | 直接把服务名和参数发给 NearWork，让它写进配置并提示你重启 |

插件市场里已有的精选条目覆盖浏览器自动化（Chrome DevTools、Playwright）、文档知识（Context7、DeepWiki）、协作（Notion、Linear、Slack）、数据（MongoDB、Supabase、Pinecone）等分类，条目随客户端版本更新。

## 配置文件在哪

配置分两级，**项目级覆盖用户级**，同名服务以项目级为准：

| 级别 | 主路径 | 兼容路径（历史原因仍会读取） |
|---|---|---|
| 用户级（全局） | `<LINGXI_HOME>/mcp.json` | `~/.claude/mcp.json` |
| 项目级 | `<项目>/.lingxi/mcp.json` | `.claude/mcp.json`、`.agent/mcp.json` |

`<LINGXI_HOME>` 默认是 `~/.LingXi`（Windows：`C:\Users\<你的用户名>\.LingXi`），可用环境变量覆盖。

> 项目级配置只在「当前工作目录」命中时才加载。如果你把配置写进了项目，记得在 NearWork 里把工作目录切到那个项目，否则看不到对应工具。

## mcp.json 写法

一个文件里可以放多个服务，键名就是服务名：

```json
{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "my-remote": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}
```

- `type`：`stdio` 或 `http`。省略时 NearWork 会根据有没有 `command` / `url` 自动推断，但建议显式写。
- `command` / `args` / `env`：stdio 服务的启动命令与环境变量。
- `url` / `headers`：HTTP 服务的端点与鉴权头。

改完配置需要重启客户端（或重新加载插件）才会生效。

## 一个容易被误解的点：MCP 工具不是一开始就在

NearWork 不会在冷启动时把所有 MCP 工具塞进上下文——那样会吃掉大量 token，还会让 AI 在几十个工具里乱选。实际机制是：

1. 启动时只加载「插件清单」（有哪些服务、各有什么工具）；
2. AI 判断当前任务需要某个服务时，先按需启用，再调用具体工具；
3. 你也可以在对话里直接点名，例如「用 Context7 查一下 Next.js 15 的缓存 API」。

CLI 里可以用 `/mcp list` 查看已接服务、`/mcp tools` 查看某个服务的工具列表。

## 常见问题

### 装完插件，AI 一直说没有这个工具？

按这个顺序排查：① 是否重启过客户端；② 服务名是否拼错（`mcp.json` 里的键名就是服务名）；③ stdio 服务是否依赖 `npx` 且本机 Node 版本过低（客户端本身要求 Node.js 22+，stdio 服务也跑在这个运行时里）；④ 项目级配置是否因为工作目录不对而没被加载。

### 第一次调用特别慢，甚至超时？

stdio 服务大多靠 `npx` 现场下载 npm 包，首次启动要拉依赖，慢是正常的。国内网络可以先设置淘宝镜像（`npm config set registry https://registry.npmmirror.com`），再重试。

### 远程 HTTP 服务连不上？

NearWork 的 MCP 客户端只支持「静态令牌」类鉴权（如 `Authorization: Bearer xxx`），不支持需要网页跳转授权的 OAuth 流程。如果对方服务强制 OAuth，装上也用不了，建议改用 stdio 版本或换服务。

## 安全提醒

MCP 服务本质上是在你电脑上运行的第三方程序：stdio 服务能执行任意命令，HTTP 服务能读写它被授权的数据。**只装你信任来源的插件**，不要为了让 AI「更聪明」而随手粘贴来源不明的配置；涉及删除、覆盖的操作，保持默认权限模式（写入需确认）更稳妥。

## 下一步

- 想了解工具权限与危险操作拦截？看[数据与隐私说明](/docs/faq/data-privacy)。
- 刚装好还不熟？回[快速开始](/docs/start/quick-start)。
- 想知道这些工具调用怎么计费、额度怎么算？见[定价页](/pricing)。
