企业官网建设流程全解析

• 教程
• 文档

本文以 easy-vibe 开源仓库中 MCP 与 Claude Code 完全指南 为核心骨架，结合仓库内真实的 MCP 配置文件与协议原理附录，为你系统讲解MCP（Model Context Protocol）是什么、为什么要在 Claude Code 中使用它、如何完成从入门到生产级的配置与排错。读完本文，你将掌握用户级/项目级配置的差异、三种传输模式（STDIO / HTTP / SSE）的适用场景、用自然语言管理 MCP 服务器的完整工作流，以及环境变量加密、版本锁定等工程化最佳实践，并能在自己的 vibe coding 项目中立刻落地一套可复用的 MCP 配置。

什么是 Claude Code MCP？

Claude Code是 Anthropic 官方的命令行 AI 编程工具，而MCP（Model Context Protocol，模型上下文协议）是让 Claude Code 连接外部工具与服务的开放协议。

简单来说，MCP 把 Claude Code 从一个"只能读写本地文件的 AI 助手"升级为"可以访问 GitHub、数据库、外部 API 与云服务的超级助手"。它是当前 vibe coding 工作流中扩展 AI 编程工具能力边界的核心技术之一，在 easy-vibe 的第三阶段（高级进阶）课程中被列为核心技能，与 Claude Code 基础、Skills、Agent Teams 等主题并列，参见 docs/ar-sa/stage-3/index.md。

从仓库附录 AI 智能体协议原理：MCP 与 A2A 中可以了解到 MCP 的关键事实背景：

• 发起方：Anthropic；
• 发布日期：2024 年 11 月 25 日；
• 开源许可：MIT License；
• 核心价值：让工具开发者"一次编写，处处使用"——只要实现一次 MCP Server，所有兼容 MCP 的 AI 应用（Claude、Cursor、Windsurf 等）都能直接调用。

MCP 之所以叫"上下文（Context）协议"，核心思路是让 AI 按需动态获取完成任务所需的上下文信息，而不是把所有信息都硬塞进 Prompt。例如当 AI 需要读取文件时，无需你复制粘贴文件内容，它可以直接通过 MCP 访问文件系统。附录中给出了协议的分层定位：

MCP 就像一个"AI 世界的 USB-C 接口"：过去每个设备都有自己的充电口（每种工具都要单独写集成代码），而 MCP 统一了 AI 连接所有工具的接口标准。附录中还总结了 MCP 的三大核心能力：

• Tools（工具）：AI 可以调用的函数，如查天气、发邮件；
• Resources（资源）：AI 可以读取的数据，如文件内容、数据库记录；
• Prompts（提示词模板）：预先定义的提示词模板，如代码审查模板、写作模板。

为什么在 Claude Code 中使用 MCP？

没有 MCP 的 Claude Code

你能做的事： ✓ 读取本地文件 ✓ 修改代码 ✓ 运行命令 ✓ 使用 Bash 工具 你不能做的事： ✗ 查看你的 GitHub Issues ✗ 访问云数据库 ✗ 调用外部 API ✗ 获取实时天气

有 MCP 的 Claude Code

你能做的事： ✓ 以上所有原生功能 ✓ 查看 / 创建 GitHub Issues 和 PRs ✓ 查询 SQLite、PostgreSQL 数据库 ✓ 访问 Notion、Slack 等外部服务 ✓ 获取实时天气与地图数据 ✓ 浏览器自动化 ✓ ……以及更多

两者的差距正是 vibe coding 从"写代码"走向"做产品"的关键：接入 MCP 后，AI 不再只是一个代码编辑器，而是一个能操作真实开发工作流的 Agent。

快速上手

第 1 步：弄清配置文件的位置

Claude Code 的 MCP 配置文件位于两个层级：

建议优先使用项目级配置，这样不同项目可以使用不同的 MCP 服务，互不干扰。

第 2 步：用自然语言添加 MCP 服务器

在 Claude Code 中，你不需要手动编辑配置文件或死记命令，直接用自然语言描述你的需求即可：

你：帮我添加一个 GitHub MCP 服务器，我的 token 是 ghp_xxx Claude：我来帮你配置 GitHub MCP 服务器…… [自动更新 .claude/mcp.json]

你：添加一个 SQLite 数据库服务器，数据库文件在 ./data/app.db Claude：好的，我来配置 SQLite MCP 服务器……

你：添加一个 HTTP 类型的 MCP 服务器，地址是 https://api.example.com/mcp Claude：我来添加这个远程 MCP 服务器……

第 3 步：验证配置

直接向 Claude Code 询问当前可用的服务器：

你：现在有哪些可用的 MCP 服务器？ Claude：当前已配置的 MCP 服务器： • github - GitHub 集成 • sqlite - SQLite 数据库 • filesystem - 文件系统访问

也可以使用诊断命令：

/doctor

第 4 步：开始使用

配置成功后，即可直接用自然语言调用 MCP 功能：

你：帮我在 GitHub 上创建一个 Issue Claude：我可以帮你创建 GitHub Issue，请告诉我： - 仓库地址，例如 owner/repo - Issue 标题 - Issue 描述

在 Claude Code 中用自然语言管理 MCP

你可以全程用自然语言与 Claude Code 交互来管理服务器，无需记住任何子命令：

你：列出所有已配置的 MCP 服务器 你：检查 MCP 服务器的连接状态 你：删除名为 notion 的 MCP 服务器 你：更新 github 服务器的 token

当遇到问题时，同样可以直接求助：

你：检查一下 MCP 连接出了什么问题 Claude：[会自动运行诊断，分析配置文件，检查服务器状态]

配置方式详解

用户级配置（全局）

编辑~/.claude.json，对所有项目生效：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token" } } } }

项目级配置（推荐）

编辑项目根目录下的.claude/mcp.json，仅对当前项目生效：

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

项目级配置的优势：

• 团队成员可以通过 Git 提交共享配置；
• 不同项目可以使用不同的 MCP 服务；
• 配置更灵活，不会污染全局设置。

三种传输模式

Claude Code 支持三种 MCP 传输模式：

STDIO：本地进程

通过command+args启动本地子进程，适合本地工具：

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

HTTP：远程服务

通过url连接远程 HTTP 服务，适合部署在服务器上的共享服务，可通过headers携带鉴权信息：

{ "mcpServers": { "remote-api": { "url": "https://api.example.com/mcp", "transport": "http", "headers": { "Authorization": "Bearer your-token" } } } }

SSE：服务器推送事件

通过 Server-Sent Events 建立单向服务端推送连接，适合流式事件场景：

{ "mcpServers": { "streaming": { "url": "https://api.example.com/sse", "transport": "sse" } } }

仓库内的真实 MCP 配置：easy-vibe 的 config/mcporter.json

为了印证上述配置理论，easy-vibe 仓库自身就携带了一份真实的 MCP 配置：config/mcporter.json。它使用了基于command的 STDIO 传输模式（即"本地进程"类型），注册了一个浏览器 Agent 服务：

{ "mcpServers": { "autoglm-browser-agent": { "command": "/Users/sanbu/.agents/skills/autoglm-browser-agent/dist/mcp_server --start_url https://www.bing.com --window_width 1456 --window_height 819 --resize_width 1456 --resize_height 819 --max_steps 100 --log_dir /Users/sanbu/.agents/skills/autoglm-browser-agent/mcp_output --if_subagent" } }, "imports": [] }

这份配置与上文"项目级配置"的 JSON 结构完全一致：mcpServers对象下以服务器名为键，值包含启动命令与参数。各启动参数的含义从命名可以推断：

• --start_url：浏览器代理启动后打开的首个页面地址；
• --window_width/--window_height：浏览器窗口的宽高；
• --resize_width/--resize_height：浏览器视口调整后的目标宽高；
• --max_steps：单次任务允许执行的最大步数上限（100 步）；
• --log_dir：运行日志的输出目录；
• --if_subagent：是否以子代理模式运行；
• imports: []：空数组表示不导入其他配置来源，仅使用当前文件声明的服务器。

需要注意两点：该配置中的command直接指向本机绝对路径（/Users/sanbu/.agents/...），属于个人机器上的环境依赖，换机使用需要同步调整路径；同时--start_url指向的外部站点仅为该浏览器代理工具的启动参数，与本仓库文档内容无关。这正好印证了原指南"不要硬编码、要可移植"的实践主张——将路径与密钥交给环境管理，才能让团队共享配置而无需逐人手工修改。

实战示例

示例 1：自动化 GitHub 工作流

你：帮我把当前改动推送到 GitHub，然后创建一个标题为 "Add new feature" 的 PR Claude： 1. 检查当前 git 状态…… 2. 创建新分支 feature/new-feature…… 3. 提交改动…… 4. 推送到远端…… 5. 调用 github_create_pull_request 创建 PR…… 6. PR 已创建：owner/repo 的 pull request #123

示例 2：数据库查询

你：查询数据库中最近注册的 10 个用户 Claude： 1. 连接 SQLite 数据库…… 2. 执行查询：SELECT * FROM users ORDER BY created_at DESC LIMIT 10 3. 返回结果： - 张三 (zhang@example.com) - 2025-02-28 - 李四 (li@example.com) - 2025-02-27 ……

示例 3：网页截图分析

你：打开 https://example.com，截图并分析页面设计 Claude： 1. 启动浏览器…… 2. 导航到 https://example.com…… 3. 截取屏幕…… 4. [返回截图] 5. 页面设计分析： - 布局采用居中设计，最大宽度 1200px - 主色调为蓝色 (#3b82f6) - 导航栏固定于顶部 ……

示例 4：与 Notion 集成

你：把刚才写的笔记保存到 Notion Claude： 1. 调用 Notion MCP 服务器…… 2. 创建新页面…… 3. 已保存：notion.so 页面 xxx

调试技巧

用自然语言诊断

当出错时，直接告诉 Claude Code：

你：我的 MCP 服务器连不上，帮我检查一下 你：GitHub MCP 工具调用失败了，是什么原因？ 你：为什么 sqlite 服务器一直显示 "connecting"？

Claude Code 会自动执行以下步骤：

1. 检查配置文件格式；
2. 校验环境变量；
3. 测试服务器连接；
4. 给出具体的修复建议。

常见问题排查

手动诊断命令

/doctor

示例输出：

系统诊断报告： =============== Claude Code: v2.5.0 ✓ Node.js: v20.0.0 ✓ MCP 服务器状态： • github: ✓ 已连接（12 个工具） • sqlite: ✗ 连接失败 - 数据库文件不存在 • puppeteer: ✓ 已连接（8 个工具） 建议： 1. 检查 sqlite 数据库路径是否正确 2. 确认 .claude/mcp.json 格式是否正确

最佳实践

1. 优先使用项目级配置

不同项目往往需要不同的 MCP 服务：前端项目可能需要浏览器测试工具，后端项目可能需要数据库连接。使用项目级配置，每个项目都可以拥有自己专属的 MCP 服务器集合，避免一个庞大全局配置造成的混乱。

更重要的是，项目级配置可以提交到 Git。团队成员克隆项目后，无需重新配置即可直接使用相同的 MCP 服务。

项目 A，前端项目 -> .claude/mcp.json 中包含浏览器测试 MCP 项目 B，后端项目 -> .claude/mcp.json 中包含数据库 MCP

2. 敏感信息存入环境变量

切勿在配置文件中硬编码密钥。配置文件可能被误提交到 Git 导致密钥泄露。正确做法是将敏感值存入环境变量，配置文件中只引用变量名：

{ "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN", "GITHUB_TOKEN": "ghp_abc123" } }

第一种写法（从环境变量读取）是正确的；第二种写法（直接硬编码密钥）是错误示范。即便配置文件公开，真正的密钥仍然隐藏在环境变量中。

3. 锁定服务器版本

默认情况下，npx -y总是使用 MCP 服务器的最新版本。这可能带来问题：新版本可能引入破坏性变更，或某个包突然被移除、改名。通过在包名后追加@version，可以确保始终使用已验证的版本，减少自动升级带来的意外：

{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github@1.2.3"] }

4. 为 MCP 配置写文档

当项目包含多个 MCP 服务器时，新成员可能不清楚每个服务器的用途和所需配置。在.claude/目录下创建README.md，说明每个服务器的用途、所需配置以及如何获取凭据，可以大幅降低沟通成本：

# MCP 配置说明 本项目使用的 MCP 服务器： ## github 用于 GitHub 自动化，需要 GITHUB_TOKEN。 ## sqlite 连接 ./data/app.db，用于查询和修改数据。 ## puppeteer 用于 E2E 测试。

Claude Code 与 Claude Desktop 对比

常用 MCP 服务器

💡 完整的 MCP 协议原理、内部实现与 A2A 对比，请参阅仓库附录：AI 智能体协议原理：MCP 与 A2A

GitHub 服务器

功能：Issues、PRs、仓库管理

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

获取 Token：在 GitHub 账户设置的 Token 管理页面生成 Personal Access Token，建议按最小权限原则分配权限。

SQLite 服务器

功能：查询和管理 SQLite 数据库

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

文件系统服务器

功能：访问指定目录内的文件

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

Puppeteer 浏览器自动化

功能：浏览器控制、截图、自动化测试

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

Brave 搜索服务器

功能：网络搜索

{ "mcpServers": { "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"], "env": { "BRAVE_API_KEY": "your-brave-api-key" } } } }

参考资源

• 协议原理深度阅读：仓库附录 AI 智能体协议原理：MCP 与 A2A，涵盖 MCP 的发布背景、内部实现、与 Function Call / A2A 的层级关系，以及典型应用场景（本地文件操作、数据库查询、API 调用、开发工具集成）；
• 官方资源：MCP 官方文档、官方规范文档与官方开源组织（modelcontextprotocol），以及官方参考服务器实现（GitHub、SQLite、PostgreSQL、Filesystem、Puppeteer、Fetch、Brave Search、Git）；
• 生态资源：社区维护的 Awesome MCP Servers 清单、官方 MCP Registry 目录、MCP.so、Smithery 等社区服务器市场，以及地图/天气类 MCP 服务器（高德、腾讯位置服务、彩云天气、OpenWeatherMap）等，均可作为扩展选型参考。

至此，你已经完整掌握了 MCP 从协议原理到生产级配置的全链路知识：理解了 MCP 为什么被称为"AI 世界的 USB-C"；学会了用户级与项目级两种配置方式与三种传输模式；见证了 easy-vibe 仓库中真实 MCP 配置文件的写法；并掌握了自然语言管理、/doctor排错、环境变量保护密钥与版本锁定等工程实践。接下来，你可以在自己的 vibe coding 项目中按"先项目级配置、再锁定版本、后写文档"的顺序，为 AI 编程工具接上第一组外部能力。

• 教程
• 文档