MCP 集成指南：将 AI Agent 连接到工具

什么是 MCP 集成，哪些环节必须正常工作？

MCP 集成通过独立的客户端连接，把 AI Host 与一个或多个 MCP 服务器连接起来。完整集成必须完成协议初始化、能力协商、类型化工具或资源发现、访问授权、调用执行、结果验证和生命周期故障处理，而不只是启动服务器进程。

MCP 是连接 AI 应用与外部系统的开放协议。官方架构区分 Host、每个 Server 对应的独立 Client 连接、Server、JSON-RPC 数据层和传输层（来源： MCP 架构概览）。该官方 SDK 在受支持语言中实现协议行为，而 调试指南 说明如何检查生命周期和传输故障。

MCP 标准化连接与能力契约，但不会决定 Agent 应信任哪些 工具、模型何时可以调用它们，也不会保证返回数据正确。协议集成还必须配合 高影响操作的人类批准、结果验证和运维监控。

配置前先选择 MCP 集成路径

不要只按客户端名称选择路径，而要根据部署边界和信任要求判断。编辑配置前，应明确服务器运行位置、使用的传输方式、凭据归属、哪些操作需要批准，以及如何观测故障。

如果你尚未选择服务器， 比较8个流行的MCP服务器 找到符合你使用场景的那一个。

路径 1：连接本地 stdio MCP 服务器

当单个用户或工作站以子进程方式启动可信本地服务器时，使用此路径。Host 启动命令，通过标准输入输出交换 JSON-RPC 消息，并在连接关闭时终止进程。

步骤1：找到你的Claude Desktop配置文件

Claude Desktop 在应用配置中保存本地服务器启动定义。应把该文件视为可执行配置：启用服务器前检查命令、软件包、参数、工作目录、环境变量和文件系统范围。

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

仅在 Host 文档要求时创建该文件，保持 JSON 有效，并限制文件访问权限，因为环境变量可能包含密钥。优先使用密钥引用或操作系统凭据存储，不要提交明文凭据。

步骤2：添加你的MCP服务器配置

每次只添加一个服务器。条件允许时固定经过审查的软件包版本，只传入服务器需要的目录或资源，并在让 Host 启动前手动运行启动命令。

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

步骤3：重启Claude Desktop

保存配置后重启 Host，并检查 MCP 设置或日志。服务器出现在列表中只证明进程已启动，并不证明每个工具都安全，也不代表每次调用都会成功。

确认 Host 能完成初始化、协商能力并列出工具。记录服务器公布的工具名称和输入 Schema，便于后续升级时检查契约漂移。

添加更多服务器

多个服务器会扩大能力覆盖，也会增加提示词占用、密钥暴露、启动时间和工具选择歧义。只添加当前工作区需要的服务器，并禁用未使用的写操作工具。

{
  "mcpServers": {
    "pulse": {
      "command": "npx",
      "args": ["-y", "@pulsemcp/core"]
    }
  }
}

验证你的连接

在测试自然语言任务前先验证协议：确认初始化成功、列出工具、检查每个输入 Schema，然后使用已知参数调用一个只读工具，并与源系统结果核对。

• “列出我所配置目录中的文件”
• "显示我在 GitHub 仓库中的最近提交"
• "我的已连接服务的状态如何？"

有效的冒烟测试应分别证明五件事：进程能够启动、能力协商成功、预期工具已暴露、无效参数会被拒绝、有效调用返回类型明确且不会泄露密钥。

如果连接失败

按层诊断故障：进程启动、传输帧、初始化、Schema 发现、授权、下游 API 和结果验证。保留请求 ID 与脱敏后的 stderr 日志，才能把 Host 的通用错误定位到具体层。

• 找不到配置文件： 验证路径与你的操作系统匹配（参见上述步骤 1）
• JSON 语法错误： 通过 JSON 验证器检查配置——常见错误包括尾随逗号和缺少引号
• 未安装服务器包： 运行 npx -y @modelcontextprotocol/server-filesystem，手动验证软件包能否运行
• 权限被拒绝： 在 macOS 上，请确保 Claude Desktop 在系统设置中具有文件系统访问权限

切换服务器

按任务启用服务器，并让具备写权限的工具始终经过明确确认。工具描述只是提供给模型的说明，不是安全边界；作用域、路径白名单和授权必须在代码中强制执行。

IDE Host 通常同时支持项目级和用户级配置。可移植且不含密钥的配置可以放入项目，凭据应放在环境变量或获批的密钥存储中，绝不能把令牌提交到仓库。

步骤 1：创建 Cursor MCP 配置目录

在你的项目根目录中，创建一个 .cursor 文件夹（如不存在）。然后在其中创建 mcp.json:

mkdir -p .cursor
touch .cursor/mcp.json

步骤 2：添加 MCP 服务器配置

编辑 .cursor/mcp.json ，加入所需服务器。下面的配置同时连接 filesystem 和 GitHub：

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

步骤 3：重启 Cursor

修改配置后重新加载 Cursor，并检查 MCP 设置面板。确认目标作用域已生效、命令能在 Cursor 环境中解析，且没有重复的服务器名称覆盖其他定义。

验证你的连接

先进行只读且结果确定的调用。请求一个已知文件或仓库事实，在批准前检查拟调用的工具和参数，并将返回值与源系统核对。

如果工具发现正常但执行失败，应区分 Schema 错误、权限错误和下游故障。检查 Host 日志、服务器 stderr、必需环境变量、可执行文件路径和软件包版本。

其他支持 MCP 的 AI IDE

其他支持 MCP 的 IDE 在配置作用域、远程服务器支持、批准交互和密钥处理上并不相同。应查看各 Host 的最新文档，不要假设所有客户端都接受相同的文件路径或字段。

• Windsurf： 使用 ~/.windsurf/mcp.json用于全局配置，或.windsurf/mcp.json用于项目本地配置
• VS Code with Copilot： MCP 支持为实验性；请查看 VS Code 扩展文档 用于设置
• JetBrains AI Assistant： 配置因 IDE 版本而异；请参阅 JetBrains 文档

核心配置格式（mcpServers JSON 对象）在这些工具中较为常见，但仍应根据具体 Host 文档验证字段和行为。

路径 2：在 Cursor 和其他 IDE 中连接 MCP

当工具应跟随代码仓库或开发工作区时，使用 IDE 作用域集成。这有利于移植，但共享配置必须遵循最小权限原则，并且不能包含用户凭据。

为何在 MCP 中选用 Cursor 而非 Claude Desktop？

当 MCP 调用参与代码导航、问题调查、测试和仓库工作流时，Cursor 很适合。关键并非编辑器品牌，而是项目是否可以声明工具，以及每位开发者如何安全提供凭据。

为破坏性操作定义批准规则，缩小仓库与账户作用域，并记录哪些工具结果可以进入模型上下文。对于受监管的代码或数据，启用服务器前应确认留存和远程处理边界。

步骤 1：创建 Cursor MCP 配置目录

在你的项目根目录中，创建一个 .cursor 文件夹（如不存在）。然后在其中创建 mcp.json:

# 创建配置目录和文件
mkdir -p .cursor
touch .cursor/mcp.json

步骤 2：添加 MCP 服务器配置

编辑 .cursor/mcp.json ，加入所需服务器。下面的配置通过认证同时连接 filesystem 和 GitHub：

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

步骤 3：重启 Cursor

重新加载 IDE 后，核对服务器身份、公布的能力和准确的工具 Schema。不要仅因自然语言描述听起来正确就批准调用。

执行已知答案测试、无效输入测试、权限拒绝测试和超时测试。这四种情况比单次成功演示更能说明生产可用性。

添加环境特定配置

开发和生产环境应使用不同身份，不要通过交换含密钥的文件来切换环境。使用环境专用密钥存储、不同作用域和明确的服务器版本，并确保共享项目配置不含凭据。

• .cursor/mcp.json——开发配置（含调试工具）
• .cursor/mcp.prod.json——生产配置（含监控工具）

在启动命令或部署系统中明确选择环境；缺少必要密钥或端点时应安全失败，而不是降级到不明确的默认值。

常用 Cursor MCP 场景

团队通常在 IDE 中使用 MCP 进行仓库搜索、问题上下文获取、文档查询、测试执行、数据库检查和部署诊断。条件允许时，应把修改类工具与只读发现工具分开。

• 代码审查自动化： 连接 GitHub 服务器以自动获取 PR 详情并建议审查
• 文档生成： 连接内部 wiki 或 Confluence 以生成上下文感知文档
• 数据库查询： 连接到封装内部数据工具的 MCP 服务器
• API 测试： 连接 HTTP 请求工具以在 IDE 中直接测试 API

其他支持 MCP 的 AI IDE

各 IDE 的支持细节变化很快。应根据当前 Host 文档确认配置位置、传输支持、授权、企业策略控制和用户批准行为。

• Windsurf： 使用 ~/.windsurf/mcp.json用于全局配置，或.windsurf/mcp.json用于项目本地配置
• VS Code with Copilot： MCP 支持为实验性；请查看 VS Code 扩展文档 用于设置
• JetBrains AI Assistant： 配置因 IDE 版本而异；请参阅 JetBrains 文档

核心配置格式（mcpServers JSON 对象）在这些工具中较为常见，但仍应根据具体 Host 文档验证字段和行为。

路径 3：使用官方 SDK 构建 MCP 服务器

当没有维护良好的实现能够提供所需操作和信任边界时，才构建服务器。官方 SDK 覆盖 TypeScript、Python、C#、Go 等语言的客户端和服务器；应根据运行时归属和部署约束选择。

步骤 1：安装 FastMCP SDK

使用官方且持续维护的 SDK，并固定经过测试的版本。定义服务器名称和版本，然后只实现工作流真正需要的最小工具集合。

# Python
pip install fastmcp

# TypeScript / Node.js
npm install @modelcontextprotocol/sdk

步骤2：定义工具处理器

使用类型明确的输入 Schema、清晰描述、受限输出、明确错误结果，并为下游调用设置超时。工具注解有助于客户端展示风险，但不能替代授权或服务器端验证。

from fastmcp import FastMCP

mcp = FastMCP("my-data-tool")

@mcp.tool()
def analyze_data(query: str, timeframe: str = "7d") -> str:
    """Analyze data from your internal database.

    Args:
        query: The analysis question
        timeframe: Time window (1d, 7d, 30d)
    """
        # Your custom logic here
    results = f"Analysis for {query} over {timeframe}: [data]"
    return results

@mcp.resource("database://schema")
def get_schema():
    return "Table: users | Columns: id, name, email, created_at"

mcp.run()

步骤3：启动服务器并连接

对于 stdio，应由 Host 启动服务器，并将 stdout 专用于协议消息，诊断写入 stderr。远程部署应提供 Streamable HTTP、实现文档规定的授权流程，并测试并发客户端和重连。

# Run your server
python my_server.py

# Add to Claude Desktop config (~/.config/Claude/claude_desktop_config.json)
{
  "mcpServers": {
    "my-data-tool": {
      "command": "python",
      "args": ["/path/to/my_server.py"]
    }
  }
}

何时选择路径3

当你需要内部业务逻辑、受控数据边界、稳定 Schema 或第三方服务器无法提供的可审计性时，应构建自定义服务器。同时要为依赖更新、协议兼容、可观测性和事件响应预留成本。

如果已有维护良好的服务器满足操作和信任边界，应优先集成并测试，而不是重复构建。托管发现可以降低搜索成本，但不能免除 Schema 与权限检查。

有关MCP服务器选项（包括预构建服务器）的完整对比， 请参阅我们的服务器指南.

路径 4：将 QVeris 作为托管能力层接入

当 Agent 需要发现并检查大量外部数据或工具能力时，可将 QVeris 作为互补的能力发现与路由层。边界要明确：MCP 定义连接协议；QVeris 通过其支持的接口帮助发现、检查和调用能力。

QVeris与手动MCP服务器设置的区别

直接 MCP 集成通常让每个服务器拥有独立进程或端点、凭据、作用域、生命周期、日志和升级策略。这种隔离增强控制力，但服务器数量增加时运维工作也会增加。

• 用于文件操作的文件系统服务器
• 用于仓库访问的 GitHub 服务器
• 用于团队沟通的 Slack 服务器
• 用于数据查询的数据库服务器
• ...以此类推，每个工具都需要对应服务器

托管能力层可以集中发现与调用模式，但也会增加依赖。生产使用前应验证支持的操作、提供商来源、数据处理、认证、配额、延迟、故障行为和退出策略。

步骤1：安装 QVeris CLI

安装 QVeris 文档指定的 CLI 软件包，核对发布者和版本，并通过常规依赖管理流程固定生产版本。

npm install -g @qverisai/cli

# 或使用 npx 无需安装
npx -y @qverisai/cli --version

步骤2：获取 API 密钥

通过 QVeris 官方控制台创建账户并获取凭据： qveris.ai。密钥不得进入源代码仓库，应使用最小可用作用域；任何出现在日志、截图或提交文件中的凭据都应立即轮换。

步骤3：将 QVeris 添加到 MCP 配置

把 QVeris 文档指定的 MCP 服务器软件包加入 Host 配置，并在部署前根据最新 QVeris 文档核对软件包名称和启动命令。

// QVeris：一个配置，many 能力
{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp-server"],
      "env": {
        "QVERIS_API_KEY": "your-api-key"
      }
    }
  }
}

连接后先发现候选能力，检查所选能力的 Schema 和提供商说明，再使用验证后的参数调用。连接成功并不代表每个下游能力都适合当前任务。

理解能力路由

能力路由从任务需求出发，而不是从记住的提供商名称出发。生产策略仍应在选择前按数据来源、时效性、区域、成本、延迟、认证和允许操作过滤候选能力。

• "我需要查看东京的天气" → 路由到天气能力
• "获取当前比特币价格" → 路由到加密货币能力
• "搜索关于 AI 的最新新闻" → 路由到搜索能力

集中发现可以减少目录维护工作，但责任仍在应用方。应验证输入输出、附加来源信息、设置预算与超时、脱敏密钥，并为关键任务定义确定性回退。

何时选择 QVeris 能力路由而非手动 MCP 设置

当大量只读能力共享同一治理模型且团队重视集中发现时，可以考虑托管层。如果必须隔离、本地执行、自定义授权或确定性选择提供商，则应优先直接服务器。

• 你需要 10 项以上能力： 安装和维护 10 个单独的 MCP 服务器需要数小时；QVeris 能力路由通过一行配置即可解决。
• 你的工具缺乏官方 MCP 服务器： 许多内部工具、遗留系统和细分服务没有公开发布的 MCP 服务器。QVeris 的能力路由可通过其托管集成连接到这些服务。
• 你想要集中式认证： 无需为每个 MCP 服务器管理单独的 API 密钥，QVeris 能力路由使用单一认证流程。
• 你正在快速原型开发： QVeris 能力路由让你在确定具体服务器配置之前探索可用能力。

直接路径和托管路径可以共存。敏感或破坏性集成应保持隔离，托管层用于已批准的发现型能力。明确记录每条路径由谁负责认证、验证、日志和事件响应。

步骤4：使用 QVeris 能力

调用前使用文档规定的发现和检查命令识别能力。把所选能力标识、输入 Schema、提供商、预期单位和验证规则保存在工作流定义中。

# 列出可用能力
qveris discover "file operations" --json

# 查询财务数据
qveris discover "cryptocurrency market data" --json

# 访问地图和位置服务
qveris discover "geographic data" --json

比较四种路径

应按部署边界、传输方式、凭据归属、运维责任和控制力比较四条路径，而不是依据乐观的配置耗时承诺。

如需全面比较 MCP 服务器选项（包括预构建服务器和托管方式）， 请参阅我们的服务器指南.

常见问题

相关指南