MCP Server 接入实战: 9种平台配置差异与凭证安全

**摘要：**本文按各平台官方文档逐一核实（2026-09），系统梳理 MCP（Model Context Protocol）配置的核心概念与实战要点。文章先厘清 MCP 配置的本质------在每个客户端自己的配置文件中声明启动哪个 server、怎么连、带什么环境变量；随后给出 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Codex CLI、Gemini CLI、Hermes Agent、OpenClaw、DSH 共 9 个平台的配置文件位置、顶层键名与最小配置示例，并重点提示各平台最容易踩的路径坑。接着从数据上下文、工具与操作、感知交互、记忆状态四个维度说明 MCP 能扩展什么，并以收发邮件为例演示敏感凭证的安全姿势。最后介绍 MCP Server 的四类来源（官方参考实现、社区开源、SaaS 官方、自研）与通用接入四步范式，给出选型建议。

你在 Claude 里配好的 MCP server，搬到 Cursor 或 VS Code 上死活不生效；网上教程给的路径五花八门，有的还把 Claude Code 的用户级配置写错位置。这篇按各平台官方文档逐一核实 （2026-09），给你一张 9 平台对照表、每家的最小配置示例、最容易踩的路径坑（比如 Claude Code 的 ~/.claude/mcp.json 是官方明确不读取的路径），以及凭证安全的正确姿势。你读完能直接照抄配置，让 Agent 用上外部工具。

关键字： MCP；Model Context Protocol；Claude Code；Cursor；VS Code；Hermes Agent；OpenClaw；Agent 配置

9平台MCPserver配置快速对照表

平台	配置文件位置	顶层键	备注
Claude Desktop	macOS `~/Library/Application Support/Claude/claude_desktop_config.json`；Win `%APPDATA%\Claude\...`；Linux `~/.config/Claude/...`	`mcpServers`	Settings → Developer → Edit Config 直达
Claude Code	项目 `.mcp.json`；用户级 `~/.claude.json`	`mcpServers`	三 scope；`~/.claude/mcp.json` 官方明确不读取
Cursor	项目 `.cursor/mcp.json`；全局 `~/.cursor/mcp.json`	`mcpServers`	两文件合并、项目级优先；支持 `${env:}` 插值
VS Code (Copilot)	工作区 `.vscode/mcp.json`；用户 profile（MCP: Open User Configuration）	`servers`	写错 key 静默忽略；`inputs` 存密钥；1.99+
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`	远程用 `serverUrl`；`${env:}`+`${file:}` 插值
Codex CLI	`~/.codex/config.toml`	TOML 表 `[mcp_servers.<name>]`	与 ChatGPT 桌面版共用；项目级仅受信项目加载
Gemini CLI	`~/.gemini/settings.json` / `.gemini/settings.json`	`mcpServers`	stdio 与 HTTP 同文件
Hermes Agent	`~/.hermes/config.yaml`	YAML `mcp_servers:`	安装时工具勾选；`tools.include` 过滤
OpenClaw	`~/.openclaw/openclaw.json`	`mcp.servers`（JSON5）	`openclaw mcp` CLI 全家桶
DSH	`~/.dsh/profiles/<profile>/cordis.patch.yml`	YAML patch 层	插件式；默认零 MCP（安全设计）

一张表看懂共性与差异：概念模型是统一的 （每个 server 一条：transport + 启动命令/URL + 环境变量），差异在文件路径、格式（JSON/TOML/YAML/JSON5）和顶层键名。从 Cursor 迁移到 VS Code，最大的改动就是把 mcpServers 改成 servers。

一、先弄清一个容易混淆的问题：MCP 配置到底管什么

MCP（Model Context Protocol）服务器是 AI Agent 与外部世界之间的标准化通用接口------它把"能力"从模型本身解耦出来，Agent 以插件化方式获得扩展。但很多教程一上来就贴 JSON，没说清一个关键区分：

MCP 配置文件 告诉客户端 （Claude Desktop、Cursor、VS Code......）启动哪些 server 进程------这是运维层面的事；
tool calling format （工具的 schema 描述）是模型推理层面的事，由客户端自动桥接------你不需要手动管理。

所以 MCP 配置的本质就一句话：在每个客户端自己的配置文件里，声明"启动哪个 server、怎么连、带什么环境变量"。真正的坑不在协议，而在各家路径和格式不统一。下面逐个平台讲。

1.1 Claude（Desktop + Code）

Claude Desktop 用单一 JSON 文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json
最快入口：应用内 Settings → Developer → Edit Config 直达这个文件

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
}
}
}

三个实操坑（2026 高频）：

command 写绝对路径 （如 /usr/local/bin/npx）------Claude Desktop 以精简 PATH 启动，裸 npx 常见 spawn npx ENOENT；Windows 上包一层 "command": "cmd", "args": ["/c", "npx", ...]
保存后完全退出重启（macOS ⌘Q / Windows 托盘右键退出）------只关窗口不重载配置
远程 server 写 "type": "streamable-http" + url（可选 headers），本地进程才写 command/args

Claude Code（CLI） 的 scope 模型最容易配错，三种 scope、两个文件：

Scope	生效范围	存储位置
local（默认）	当前项目	`~/.claude.json` 内当前项目的条目
project	当前项目，可随 git 分享	项目根 `.mcp.json`
user	所有项目全局生效	`~/.claude.json` 顶层 `mcpServers` key

添加命令：claude mcp add <name> -- <command> [args...]，用 --scope project / --scope user 切换
查看已配：claude mcp list

🔴 最常见的错误配置 ：网上大量教程写"用户级全局配置在 ~/.claude/mcp.json"------官方文档明确列出 Claude Code 不读取 这个路径（也不读 ~/.claude/.mcp.json、~/.claude/config/mcp.json、%APPDATA%\Claude\mcp.json）。用户级配置就在 ~/.claude.json------注意是家目录下这一个文件 ，不是 ~/.claude/ 目录里的任何文件。配错了的症状：server 永远不出现，且没有任何报错。

1.2 Cursor

Cursor 从两个位置读 mcp.json，两份合并生效：

项目级 （可随 git 分享给团队）：项目根 .cursor/mcp.json
全局（个人、所有项目）：~/.cursor/mcp.json（Windows：%USERPROFILE%\.cursor\mcp.json）
同名 server 两国都定义时，项目级优先

顶层 key 是 mcpServers，与 Claude Desktop 同构，配置可以直接复制。加分项：

支持变量插值 ：${env:NAME}、${userHome}、${workspaceFolder}------token 不用硬编码进文件
Cursor Marketplace 有 "Add to Cursor" 一键安装（含 OAuth），社区目录在 cursor.directory
改完配置在 Settings → Tools & MCP 里把 server 关掉再打开（或点刷新），这是"为什么没生效"的头号原因

{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
}
}
}
}

1.3 VS Code（Copilot）

VS Code 的坑最隐蔽：顶层 key 是 servers，不是 mcpServers。写错了 VS Code 静默忽略，一个工具都不会加载，也不报错。

工作区级 ：项目根 .vscode/mcp.json（可提交 git 分享）
用户级 ：命令面板（⇧⌘P / Ctrl+Shift+P）→ MCP: Open User Configuration，打开用户 profile 下的 mcp.json；多 profile 时每个 profile 各一份
也可走 settings.json 的 mcp 键
需要 VS Code 1.99+，工具在 Copilot 的 agent mode 里用

{
"servers": {
"filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
}
},
"inputs": [
{
"type": "promptString",
"id": "github_token",
"password": true,
"description": "GitHub PAT"
}
]
}

inputs 数组是 VS Code 独有的密钥管理：${input:github_token} 引用，弹窗输入，不落盘。

1.4 Windsurf / Codex CLI / Gemini CLI（三个 CLI 派）

Windsurf（Cascade 引擎）：

配置文件：~/.codeium/windsurf/mcp_config.json（Windows：%USERPROFILE%\.codeium\windsurf\mcp_config.json）
顶层 key mcpServers；远程 server 用 serverUrl + headers
支持两种插值：${env:VAR} 环境变量、${file:~/.secrets/api_key.txt} 直接从文件读密钥

Codex CLI（OpenAI，与 ChatGPT 桌面版、IDE 扩展共用配置）：

配置文件：~/.codex/config.toml------注意是 TOML 不是 JSON
项目级 .codex/config.toml 只在"受信任项目"里加载------克隆陌生仓库时其自带配置不会生效（安全设计）
命令添加：codex mcp add <name> -- <command>，远程用 codex mcp add <name> --url <address>
server 条目支持 enabled_tools / disabled_tools / default_tools_approval_mode（auto/prompt/approve）
默认超时：启动 10s、工具调用 60s，重 server 记得调大

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Gemini CLI（Google）：

配置文件：全局 ~/.gemini/settings.json，项目级 .gemini/settings.json
顶层 key 回到 mcpServers；stdio（command/args）与 HTTP（url/headers）写同一文件

1.5 Hermes Agent

Hermes Agent 的 MCP 支持随标准安装内置 ，配置写在 ~/.hermes/config.yaml 的 mcp_servers: 键下，本地 stdio 与远程 HTTP server 写在同一处：

复制代码

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"]

启动时自动发现并注册工具，MCP 工具像原生工具一样被 Agent 调用。按 server 过滤用 mcp_servers.<name>.tools.include；配好凭证后安装时会呈现工具勾选清单（空格切换、回车确认），只暴露你勾选的工具。官方还维护一份策展目录 ------条目经 Nous 员工审核（仓库 optional-mcps/ 目录），安装前能看到 source 链接和需要什么凭证；API key 安装时提示写入 ~/.hermes/.env，远程 server 支持 auth: oauth（首次连接开浏览器完成授权）。

1.6 OpenClaw

配置在 ~/.openclaw/openclaw.json 的 mcp.servers 键下：

复制代码

{
  mcp: {
    servers: {
      docs: {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
        enabled: true
      }
    }
  }
}

每个 server 需要一个 command（stdio）或 url（远程）；openclaw mcp list / add / probe / doctor / login 等 CLI 子命令管理全生命周期。进阶能力（如需再查文档）：headers、OAuth、TLS、超时、toolFilter 按工具名过滤。

1.7 DSH（DeepSeek Harness）

DSH 不用独立 mcp.json，MCP 通过插件 @deepseek-ai/dsh-mcp-client 挂载，配置写在 profile 的补丁层：

配置文件：~/.dsh/profiles/<profile>/cordis.patch.yml
一个插件实例连一个 server，工具注册为 mcp__<serverName>__<工具名>
支持 stdio 和 streamable-http 两种 transport
- insert:
  - id: filesystem-mcp
    name: '@deepseek-ai/dsh-mcp-client'
    config:
    transport: stdio
    serverName: filesystem
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem', '~/data']
    env: {}
    failOnStartupError: false

改完重启 dsh web 生效。注意 DSH 默认零 MCP 连接是官方安全设计------每个 server 命令都是 agent 沙箱外的可信执行代码，需要你显式启用。

1.8 mcpServers 配置模板与字段详解

前面每家给的都是最小示例，这里把通用字段集中讲透。两种形态各一个模板，覆盖 90% 的配置场景。

形态一：本地 stdio server（server 作为子进程在你机器上跑）：

复制代码

{
  "mcpServers": {
    "<server名>": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-xxx"],
      "env": {
        "API_KEY": "<凭证>"
      }
    }
  }
}

形态二：远程 HTTP server（server 部署在远端，客户端直连）：

复制代码

{
  "mcpServers": {
    "<server名>": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

逐字段解释：

字段	作用	形态	说明
`command`	启动本地 server 的可执行命令	stdio	常见值：`npx`（npm 包 server）、`python -m xxx`（PyPI 包）、`node`、`docker run`。Claude Desktop 记得写绝对路径（精简 PATH 坑见 1.1）
`args`	传给 command 的参数数组	stdio	通常是包名 + 运行参数（目录路径、`--db-path` 等）
`env`	注入 server 进程的环境变量	stdio	凭证的正规存放位 ------API key 写这里而不是拼进 args；第三章会讲更安全的 `${env:}` 引用
`cwd`	server 进程的工作目录	stdio	Cursor / Codex / DSH 支持；相对路径的解析基准
`type`	transport 类型声明	两种	VS Code 必填（`stdio` / `sse`）；Claude Desktop 远程 server 用 `streamable-http`
`transport`	同 type，OpenClaw 的字段名	两种	canonical 拼写 `streamable-http`，`http` 也接受
`url`	远程 server 的端点地址	HTTP	一般以 `/mcp` 结尾
`headers`	请求头	HTTP	认证头写这里：`Authorization: Bearer <token>`

两个容易被忽略的通用机制：

变量插值------密钥不落盘。 Cursor、Windsurf、VS Code 支持在 command/args/env/url/headers 里写 ${env:MY_TOKEN}，客户端运行时从环境变量取值，配置文件本身不含明文密钥（Windsurf 还支持 ${file:~/.secrets/api_key.txt} 从文件读）。Codex 的对应机制是 env_vars / bearer_token_env_var 字段引用环境变量名。把密钥硬编码进配置文件的写法只适合本地试验，进 git 仓库前必须换掉。
server 名就是工具的命名空间。 你给 server 起的名字会进入工具注册名：mcp__<server名>__<工具名>。两个 server 各带一个 query 工具时靠前缀区分；名字起得有意义（dev-db / prod-db），日志和权限控制都好读。__proto__ 这类保留名会被拒绝。

各平台的独有字段（VS Code 的 inputs、Codex 的 enabled_tools、DSH 的 toolCallTimeoutMs 等）见前面对应小节，这里不重复。

二、MCP 能扩展什么：四个维度 + 凭证安全实战

MCP Server 主要扩展 Agent 的四个核心方面，每个维度配一个实操场景。

2.1 数据上下文（Data & Context）

Agent 本身的知识是静态且有限的。MCP Server 允许 Agent 动态访问私有、实时或特定领域的数据源，作为上下文注入推理过程。

本地文件系统 ：让 Agent 直接读取、搜索和分析你电脑上的代码库、文档或日志（如 filesystem MCP）
数据库查询：连接 PostgreSQL、SQLite 等，让 Agent 理解表结构并执行 SQL 获取业务数据
SaaS 平台数据：接入 Notion、Google Drive、Confluence，检索企业内部知识库
实时信息流：接入股票行情、天气 API 或新闻聚合器，提供训练数据之外的实时事实

实操：连接本地 SQLite 数据库。 场景：让 Agent 分析本地的 analytics.db，回答"上个月销售额最高的产品是什么？"

第一步，启动官方 SQLite MCP Server：

复制代码

npx -y @modelcontextprotocol/server-sqlite --db-path /path/to/analytics.db

第二步，在客户端配置文件中添加：

复制代码

{
  "mcpServers": {
    "sqlite-analytics": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "/path/to/analytics.db"]
    }
  }
}

第三步，直接在对话框提问"查询 analytics 库中上月销售冠军"。Agent 会自动调用 query 工具，生成并执行 SQL，返回结构化结果而非原始数据。

关键点：Agent 不需要知道数据库密码或连接字符串，MCP Server 封装了所有连接细节，且只暴露安全的查询接口。

2.2 工具与操作能力（Tools & Actions）

最常见的扩展方式。MCP Server 将外部系统的 API 封装为标准 Tool，使 Agent 从"只能聊天"变为"能执行任务"。

开发运维：通过 GitHub/GitLab MCP 创建 PR、管理 Issue；通过 Docker/K8s MCP 部署容器或查看 Pod 状态
办公自动化：通过 Slack/飞书 MCP 发送消息、安排会议；通过 Jira MCP 更新任务状态
浏览器操控：通过 Puppeteer/Playwright MCP 让 Agent 打开网页、填写表单、截图或抓取动态渲染内容
支付与交易：在受控环境下调用 Stripe 或内部支付网关接口（需严格权限控制）

实操：通过 GitHub MCP 创建 PR。 场景：代码修改完成后，让 Agent 自动提交分支并创建 Pull Request。

第一步，获取 GitHub Personal Access Token，权限包含 repo。第二步，配置 server（Token 走环境变量）：

复制代码

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<你的PAT>"
      }
    }
  }
}

第三步，对 Agent 说："把当前 feature/login-fix 分支推送到远程，并创建一个 PR 到 main，标题是'修复登录验证逻辑'"。Agent 会依次调用 create_branch、push_commit、create_pull_request 完成任务。

关键点：Token 仅存在于 MCP Server 进程中，Agent 本身永远看不到凭证，避免密钥泄露。

2.3 感知与交互模态（Perception & Interaction）

MCP 不限于文本输入输出，还能扩展 Agent 的感知通道和反馈形式。

多模态输入：接入摄像头或屏幕共享 MCP，让 Agent "看到"当前界面或物理环境进行视觉分析
语音交互：接入 TTS/STT MCP，让 Agent 具备语音播报或语音指令识别能力
IDE 集成：在 VS Code 或 Cursor 中，通过 MCP 让 Agent 感知当前打开的文件、光标位置和编辑器状态，实现精准的代码补全或重构

实操：Puppeteer MCP 操控浏览器。 场景：让 Agent 打开竞品网站，截图并分析其定价页面布局。

第一步，安装 Puppeteer MCP Server：

复制代码

npm install -g @modelcontextprotocol/server-puppeteer

第二步，配置：

复制代码

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/global/path/to/server-puppeteer/dist/index.js"]
    }
  }
}

第三步，指令："打开 https://competitor.com/pricing ，等待页面加载完成，截取全屏图片，然后告诉我他们的企业版价格是多少"。Agent 会调用 navigate → screenshot → evaluate（提取 DOM 文本）一系列工具，并将截图作为图像上下文传回给自己做视觉分析。

关键点：突破了纯文本限制，Agent 能处理动态渲染的 SPA 页面，这是传统 API 调用无法做到的。

2.4 记忆与状态管理（Memory & State）

LLM 本身是无状态的。MCP Server 可以为 Agent 提供持久化的记忆层。

长期记忆存储：接入向量数据库（如 Chroma、Pinecone）或知识图谱 MCP，让 Agent 记住跨会话的用户偏好、历史决策或学到的新知识
会话状态同步：多 Agent 协作场景中，通过共享的 Redis/Memcached MCP 同步任务进度和中间结果
用户画像管理：连接 CRM 或用户配置服务，让 Agent 在每次对话开始时自动加载用户的个性化设置

实操：接入 ChromaDB 向量数据库。 场景：让 Agent 记住你在过去 10 次对话中提到的所有技术偏好和项目背景。

第一步，启动本地 ChromaDB 服务，安装社区 Chroma MCP Server：

复制代码

pip install mcp-server-chroma

第二步，配置：

复制代码

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["-m", "mcp_server_chroma"],
      "env": {
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000",
        "COLLECTION_NAME": "user_long_term_memory"
      }
    }
  }
}

第三步，Agent 使用方式------写入：每次对话结束时，Agent 自动调用 upsert_memory 存储关键信息（如"用户偏好 TypeScript + Bun 运行时"）；读取：新对话开始时，Agent 先调用 search_memory 检索相关上下文再开始回答，实现跨会话的个性化体验。

关键点：将非结构化对话转化为可检索的向量记忆，解决了 LLM "金鱼记忆"的根本缺陷。

四个维度的核心价值对比：

扩展维度	没有 MCP 的痛点	使用 MCP 后的优势
数据	需要手动复制粘贴或写死 API 调用	动态、安全、标准化的数据访问
工具	每个新工具都需要重新微调或硬编码	即插即用，生态共享，一次编写到处运行
感知	局限于文本对话框	融入 IDE、浏览器、操作系统等原生环境
记忆	上下文窗口用完即忘	结构化、可检索的持久化知识

2.5 敏感凭证实战：收发邮件

推荐方案是社区维护的通用邮件 Server mcp-server-email（IMAP/SMTP），支持 Gmail、Outlook、企业邮箱。

能力：读取收件箱、搜索邮件、发送邮件、管理文件夹
使用方式 ："查看今天未读邮件，摘要列出主题和发件人"、"给 alice@example.com 发一封邮件，主题是'会议纪要'"、"搜索过去一周来自 boss@company.com 的所有邮件"

{
"mcpServers": {
"email": {
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-email"],
"env": {
"EMAIL_ADDRESS": "user@gmail.com",
"EMAIL_PASSWORD": "xxxx xxxx xxxx xxxx",
"IMAP_HOST": "imap.gmail.com",
"IMAP_PORT": "993",
"SMTP_HOST": "smtp.gmail.com",
"SMTP_PORT": "587"
}
}
}
}

🔴 关键安全提示：Gmail 等主流邮箱禁止直接使用账户密码 。必须生成 App Password（应用专用密码）：Google 账户 → 安全 → 两步验证 → 应用专用密码。这个密码只能用于 SMTP/IMAP，无法登录网页，即使泄露风险也有限。

替代方案：

Server	适用场景	特点
`mcp-server-gmail` (OAuth)	个人 Gmail	OAuth2 授权，无需密码，更安全但配置复杂
`mcp-server-outlook`	Microsoft 365	Graph API + OAuth，支持日历/联系人联动
`mcp-server-resend`	仅发送	纯发送 API，适合通知类场景，无收件能力

两种场景的安全原则对比：

原则	邮件	数据库
凭证隔离	App Password / OAuth Token	API Key / Vault 注入
最小权限	仅 IMAP+SMTP，无账户管理权限	只读账号 / 限定表 / IP 白名单
可撤销性	App Password 可随时删除	API Key 可吊销，Vault 可轮换
审计	邮件服务器自带日志	数据库审计日志 + MCP Server 日志
Agent 可见性	Agent 只看到 tool schema	Agent 只看到业务级 tool，无连接信息

核心思想：MCP 的设计哲学是把**"认证"和"能力描述"**彻底分离。Agent 只需要知道"我能查销售报表"，而不需要知道"用什么密码连哪个库"。所有敏感信息都封装在 MCP Server 进程内部，这是比传统 Function Calling 更安全、更适合生产环境的架构。

三、MCP Server 从哪里来：四类来源

四类来源不改变 1.8 配置模板的结构 ，只决定你往模板空格里填什么------选哪种形态、command 还是 url、凭证放哪。先看总表再逐类展开：

来源	选哪种形态	影响的字段	典型填法
3.1 官方参考实现	stdio（形态一）	`command` + `args`	`npx -y @modelcontextprotocol/server-xxx`，凭证进 `env`
3.2 社区开源	stdio 为主	`command` + `args`	npm 包 `npx` / PyPI 包 `python -m`；凭证权限要审
3.3 SaaS 官方	两种都可能	`url` + `headers` 或 `env`	云托管直连 HTTP；厂商 npm 包装的仍 `npx` + `env`
3.4 自研	你说了算	全部字段	本地脚本 `python xxx.py` / 部署后转 HTTP；tool schema 暴露面自己定

一句话：前三类是"选货"------货的形态决定你填 command 还是 url；3.4 是"造货"------连字段怎么设计都是你定的。

3.1 官方参考实现

由 Anthropic MCP 团队维护，质量最高、文档最全，通常作为开发标杆。

仓库：modelcontextprotocol/servers (GitHub)
典型例子 ：server-filesystem（本地文件读写）、server-postgres / server-sqlite（数据库查询）、server-github（GitHub API 封装）、server-puppeteer（浏览器自动化）、server-slack（Slack 消息收发）
获取方式 ：直接 npx -y @modelcontextprotocol/server-xxx 运行，无需全局安装

3.2 社区/第三方开源 Server

由开发者或企业贡献，覆盖长尾场景，生态最活跃。

发现渠道 ：MCP Servers 目录站（mcp.so、glama.ai/mcp/servers、smithery.ai）；GitHub 搜关键词 mcp-server；npm/PyPI 搜 mcp-server-*
典型例子 ：mcp-server-chroma / mcp-server-qdrant（向量数据库记忆）、mcp-server-notion / mcp-server-confluence（知识库集成）、mcp-server-docker（容器管理）、mcp-server-brave-search（网络搜索）、@anthropic/mcp-server-fetch（网页抓取，比 Puppeteer 轻量）
注意：社区 Server 质量参差不齐，使用前务必审查源码和权限声明

怎么填模板 （以社区 Chroma server 为例，PyPI 包走 python -m）：

复制代码

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["-m", "mcp_server_chroma"],
      "env": {
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000"
      }
    }
  }
}

判别口诀：npm 包名以 @xxx/ 开头或纯小写连字符 → npx -y <包名>；PyPI 装完后 README 让你 python -m 或给了 entry point → command: python + args 带模块名。社区 server 的 env 字段名以它 README 的说明为准，没有统一规范------填之前先读它的配置文档。

3.3 SaaS 厂商官方 Server

越来越多的 SaaS 产品原生支持 MCP，作为其 API 的替代接入方式。

典型例子：Cloudflare（Workers、KV、R2 管理）、Stripe（支付、客户管理）、Linear / Jira（项目管理原生支持）、Neon / Supabase（云数据库托管 server）
优势：与平台深度集成，认证流程更规范（如 OAuth），更新与平台 API 同步

怎么填模板------先看厂商给的是哪种货，两种都有实例：

云托管（如 Neon），直接走 HTTP 形态，url 填厂商端点、headers 放 API key：

复制代码

{
  "mcpServers": {
    "neon-prod": {
      "command": "npx",
      "args": ["-y", "@neondatabase/mcp-server-neon"],
      "env": {
        "NEON_API_KEY": "neon_sk_xxxxxxxx"
      }
    }
  }
}

厂商发 npm 包装（如 Cloudflare），本质还是 stdio 进程，command/args/env 三件套：

复制代码

{
  "mcpServers": {
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "@cloudflare/mcp-server-cloudflare"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "<token>"
      }
    }
  }
}

注意上面 Neon 的例子：虽然是"云数据库厂商"，但它发的也是 npm 包装------url 直连形态多见于厂商提供托管端点时（如 https://mcp.厂商.com/mcp）。判断方法就一条：厂商文档给端点地址就走形态二，给安装命令就走形态一。

3.4 自研 MCP Server

现有 Server 无法满足需求时，用官方 SDK 自己编写。

SDK ：TypeScript @modelcontextprotocol/sdk；Python mcp（PyPI）；Kotlin / Rust / C# 社区维护
最小示例（Python）：

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-tool-server")
@mcp.tool()
def get_internal_metrics(env: str) -> dict:
"""获取内部监控指标，仅允许 prod/staging"""
if env not in ("prod", "staging"):
raise ValueError(f"非法环境: {env}")

调用内部 API...

return {"cpu": 0.45, "memory": 0.72}
if name == "main":
mcp.run(transport="stdio")
适用场景：对接公司内部系统、遗留 API、需要特殊鉴权逻辑或数据脱敏的场景

怎么填模板------自研 server 的填法取决于你把它跑在哪：

本地脚本（和 Agent 同机）→ stdio 形态，command 直接指向你的脚本：

复制代码

{
  "mcpServers": {
    "internal-db": {
      "command": "python",
      "args": ["/path/to/internal_db_mcp.py"],
      "env": {
        "VAULT_DB_PASSWORD": "<从 Vault 注入>"
      }
    }
  }
}

部署到内网服务器（多客户端共用、集中管凭证）→ server 加 transport="streamable-http" 启动，客户端改成 HTTP 形态连 url。这是自研独有的优势 ：tool schema 暴露面（哪些工具、参数怎么描述）是你设计 @mcp.tool() 装饰器时定的------Agent 能看到什么、看不到什么，从源头可控（第二章 2.5 的凭证隔离思想落地处）。

怎么判断一个 MCP Server 能不能用？

检查项	说明
传输协议	`stdio`（本地进程）还是 `sse/streamable-http`（远程服务），客户端需匹配
Tool Schema	每个 tool 必须有清晰的 `description`，这是 Agent 决策调用的唯一依据
安全声明	README 中的权限范围、是否只读、是否有破坏性操作
维护状态	最后更新时间、Issue 响应速度、Star 数
依赖审计	特别是社区 Server，检查依赖链是否有已知漏洞

实用建议：初学者从官方参考实现 入手验证流程；生产环境优先选择 SaaS 官方 Server 或自研；社区 Server 适合原型验证和个人项目，使用前务必做安全审查。

四、通用接入流程：四步范式

无论扩展哪个方面、无论哪个平台，操作都遵循同一范式：

找/写 Server：从 MCP Servers 仓库或 npm/pip 获取对应能力的 Server
配配置：在客户端的配置文件中声明 command、args、env（路径见第一章对照表）
重启客户端：让客户端初始化 MCP 连接，发现可用 Tools/Resources
自然语言驱动：无需教 Agent 如何调用，只需描述意图，Agent 根据 Tool 的 schema 描述自主决策调用链

这种**"配置即集成"**的模式，正是 MCP 相比传统 Function Calling 最大的工程价值------能力扩展不再需要改模型、改代码，只需加一条配置。

⚠️ 安全提醒：MCP Server 的扩展能力也带来安全风险。生产环境中必须实施严格的权限最小化原则 、输入验证 和审计日志，防止 Agent 被提示注入攻击诱导执行危险操作（如删除数据库、泄露敏感文件）。

五、结语与选型建议

MCP Server 把 Agent 从一个**"封闭的语言模型"变成了一个"开放的系统集成节点"**，使其能够真正嵌入到实际的工作流和业务系统中。选型上给三条直接建议：

先跑通官方参考实现（filesystem / sqlite 最简单），确认客户端配置链路没问题，再接业务 server
凭证永远走 env 变量、App Password、OAuth 或 Vault 注入------任何让你把明文密码写进配置文件推荐进生产环境的教程，直接跳过
迁移平台时先对照第一章的表格核对顶层键 ------mcpServers / servers / TOML / YAML 四种形态，key 写错是静默失败，没有报错可看

参考来源

MCP 官方规范：https://modelcontextprotocol.io
Claude Code MCP 文档：Connect Claude Code to tools via MCP - Claude Code Docs
Cursor MCP 文档：Model Context Protocol (MCP) | Cursor Docs
VS Code MCP 文档：Add and manage MCP servers in VS Code
OpenClaw MCP 文档：Connect MCP servers - OpenClaw
Hermes Agent MCP 文档：MCP (Model Context Protocol) | Hermes Agent
MCP 官方 servers 仓库：GitHub - modelcontextprotocol/servers: Model Context Protocol Servers · GitHub

MCP Server 接入实战: 9种平台配置差异与凭证安全

9平台MCPserver配置快速对照表

一、先弄清一个容易混淆的问题：MCP 配置到底管什么

1.1 Claude（Desktop + Code）

1.2 Cursor

1.3 VS Code（Copilot）

1.4 Windsurf / Codex CLI / Gemini CLI（三个 CLI 派）

1.5 Hermes Agent

1.6 OpenClaw

1.7 DSH（DeepSeek Harness）

1.8 mcpServers 配置模板与字段详解

二、MCP 能扩展什么：四个维度 + 凭证安全实战

2.1 数据上下文（Data & Context）

2.2 工具与操作能力（Tools & Actions）

2.3 感知与交互模态（Perception & Interaction）

2.4 记忆与状态管理（Memory & State）

2.5 敏感凭证实战：收发邮件

三、MCP Server 从哪里来：四类来源

3.1 官方参考实现

3.2 社区/第三方开源 Server

3.3 SaaS 厂商官方 Server

3.4 自研 MCP Server

调用内部 API...

四、通用接入流程：四步范式

五、结语与选型建议

参考来源