热点

AI SCORE

技术实践2025-04-22 21:51

MCP 完全指南：深度教程

DEV Community · Anmol Baranwal#MCP#AI Agent#深度教程

Editor brief · 编辑速览

全面讲解 Model Context Protocol 的完整指南，涵盖 Agent 多步问题解决和协调等核心概念，社区热度最高。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

AI 智能体早已超越聊天补全阶段。它们正在解决多步骤问题、协调跨越数十个应用的工作流，并真正实现自主运行。MCP——模型上下文协议（Model Context Protocol）——是许多此类突破背后的连接纽带。

但 MCP 的发展速度非常快。2025 年初的生态系统与如今推出的产品截然不同：MCP 网关、工具路由器、API 密钥强制验证、SDK 优先的工作流。如果你刚刚开始接触 MCP，或者正在补上这方面的进展，那么这正是我希望自己入门时就能读到的指南。

为什么现有的 AI 工具集成存在不足

MCP 到底是什么——核心组件详解

MCP 的底层工作原理

MCP 解决了什么问题，以及它为何重要

MCP 的三层架构（以及我最终是如何理解它们的）

使用 Composio 连接 500 多个托管 MCP 服务器（2026 年的方式）

六个包含使用场景的实用示例

值得了解的局限性

1. API 太多，上下文却远远不够

你希望 AI 智能体使用的每一种工具，本质上都是一个小型 API 集成。假设用户提出这样一个问题：“Anmol 有没有给我发过关于昨天会议报告的邮件？”

为了回答这个问题，LLM 必须意识到这是一项邮件搜索任务（而不是搜索 Slack 或 Notion），选择正确的端点，例如 search_email_messages，解析结果，再使用自然语言进行总结——而且所有这些操作都必须在其上下文窗口的范围内完成。

这会给模型带来巨大的认知负担。它们经常忘记步骤、猜测参数，或者在多步骤流程中产生幻觉。如果你无法验证结果的准确性，甚至不会意识到问题已经发生。

API 基于步骤运行，但 LLM 并不擅长记住步骤

以一次基本的 CRM 更新为例。首先，通过 get_contact_id 获取联系人 ID。然后，使用 read_contact 获取联系人数据。最后，通过 patch_contact 提交更新。在传统代码中，你会将这些步骤抽象成一个函数。但对于 LLM，每一个步骤都可能失败——参数错误、字段遗漏或者调用链中断。

脆弱的提示词工程高塔

API 会不断演进，文档会发生变化，身份验证流程也会更新。你的智能体原本运行得非常完美，却可能因为第三方做出某项改动而在一夜之间失效。与传统应用不同，这里没有共享框架或抽象层。每一种 AI 工具集成，都是由提示词工程和 JSON 拼装而成的脆弱高塔。

你的工具是为 GPT-4 构建的吗？如果改用 Claude 或 Gemini，就必须从头重写所有函数描述和系统提示词。过去一直没有通用的解决方案——直到 MCP 出现。

2. MCP 是什么？核心组件

模型上下文协议（Model Context Protocol，MCP）是一种开放协议，用于标准化应用程序向 LLM 提供上下文和工具的方式。你可以将它理解为面向 AI 智能体的通用插件系统。

借助 MCP，你的智能体可以通过 Gmail 发送邮件、在 Linear 中创建任务、在 Notion 中搜索文档、在 Slack 中发布消息，以及更新 Salesforce 中的记录——所有这些操作都可以通过标准化接口发送自然语言指令来完成。

MCP 的核心采用客户端—服务器架构，其中一个宿主应用程序可以连接多个服务器。

MCP 宿主——Claude Desktop、Cursor、Windsurf 等应用，或者任何希望通过 MCP 访问数据的 AI 工具。

MCP 客户端——与 MCP 服务器保持一对一连接的协议客户端，充当通信桥梁。

MCP 服务器——轻量级程序，每个服务器都通过标准化协议提供特定能力，例如读取文件、查询数据库或发送电子邮件。

提示词和资源——MCP 服务器能够安全访问的文件、数据库和服务。

远程服务——MCP 服务器能够连接的外部 API 和云端系统。

3. MCP 的底层工作原理

客户端就是你的应用程序——Cursor、Claude Desktop 等。它们负责向 MCP 服务器请求可用能力，将这些能力（工具、资源和提示词）呈现给 AI 模型，把 AI 的工具使用请求转发给服务器，然后返回执行结果。

MCP 服务器充当用户或 AI 与外部服务之间的中介。它们提供标准化的 JSON-RPC 接口，用于访问工具和资源；将现有 API 转换为兼容 MCP 的能力；并负责处理身份验证和通信标准。

构建模块：工具、资源和提示词

工具代表 AI 可以执行的操作，例如 search_emails 或 create_issue_linear。了解更多

资源代表 MCP 服务器向客户端提供的数据，包括文件内容、数据库记录、API 响应以及实时系统数据。每项资源都通过一个唯一 URI 标识。了解更多

提示词用于指导 AI 在使用工具时应如何行动。它们就像操作指南，帮助 AI 遵循特定的风格、工作流或安全协议。了解更多

🎯 实用示例：假设有一个 Google Calendar MCP 服务器。如果你要求 AI“重新安排我下周与 Alice 的所有会议”，它可能难以处理杂乱的 API 数据。MCP 提示词可以指示模型只修改匹配的日程，将这些日程提取到临时资源中，在那里应用变更，然后再同步回去——干净、结构化且可靠。

4. MCP 解决的问题

一种通用协议 = 数千种工具。各项服务使用一致的 JSON-RPC 格式描述自身能够执行的操作。

明确的职责分离。模型负责思考，工具负责行动。Slack 每次微调 API 时，你的智能体都不会随之崩溃。

不存在供应商锁定。将 GPT 替换为 Claude 或 Gemini 时，不必重新编写工具描述。

记忆与多步骤工作流。MCP 支持能够跨任务记忆信息并将多个操作串联起来的智能体。

减少幻觉。清晰、结构化的工具定义有助于 AI 立足事实并保持准确。

<aside> ⚡ MCP 让通用 AI 助手的梦想成为开发者能够实际实现的现实。将多个操作组合成复杂工作流，并由 AI 负责处理其中逻辑的能力，正在开启智能自动化的新时代。

5. MCP 的三层架构

⚡ 模型 ↔ 上下文：“以 LLM 能够理解的方式与它交流”

将模型想象成机器人的大脑。它能够处理信息，但需要清晰的指令。上下文负责提供这些指令。告诉机器人“给我做一个三明治”过于模糊。而说“用这些面包、火腿和奶酪做一个三明治”，则为它提供了理解并执行任务所需的上下文。

⚡ 上下文 ↔ 协议：“为 LLM 提供结构化的记忆、工具和状态”

机器人获得指令后，还需要一种遵循指令、记住细节并使用工具的方式。协议就是实现这一切的系统——它帮助机器人记住食材、了解如何使用刀具，并按顺序执行各个步骤。

⚡ 协议 ↔ 运行时：“真正运行 AI 智能体”

机器人已经知道要做什么（上下文），也知道该怎么做（协议）。现在，它需要真正采取行动。运行时就是让任务实际发生的环境——也就是完成这一切的厨房。

<aside> 🍽️ 餐厅类比：模型是厨师（知识和技能）。上下文是菜单（食材以及餐点应呈现的样子）。协议是服务员（传达点单内容并记住过敏事项）。运行时是厨房（工具、火候和准备工作汇集在一起的地方）。

使用 Composio 连接 500 多个托管 MCP Server（2026 年方案）

MCP 生态已经发生了显著变化。过去使用 npx 命令分别运行 MCP Server，并为每个应用管理独立 mcp.json 配置的方法仍然有效，但 Composio 平台带来了两项重大升级：Tool Router 和 MCP Gateway。

Tool Router（推荐）。一个 MCP 端点，可动态发现并使用来自 500 多个集成的工具。通过统一会话处理工具发现、身份验证和执行。

MCP Gateway。面向企业团队——位于 AI 智能体与工具之间的集中式控制平面，具备 SOC2/ISO 认证、RBAC 控制和审计追踪能力。

MCP API 密钥强制验证。截至 2026 年 3 月，新组织默认对所有 MCP Server 请求启用 API 密钥强制验证。

新 SDK。Composio 提供 @composio/core（TypeScript）和 composio（Python）SDK，用于以编程方式管理 MCP Server。

方案 1：Tool Router（推荐）

Tool Router 为你的智能体提供单一 MCP 端点，并内置动态工具访问和上下文管理能力。

import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });

// Create a session for a user
const session = await composio.create("user-123", {
  toolkits: ["gmail", "slack", "notion"],
});

const mcpUrl = session.mcp.url;

from composio import Composio

composio = Composio(api_key="YOUR_API_KEY")

session = composio.create(
    user_id="user-123",
    toolkits=["gmail", "slack", "notion"]
)

mcp_url = session["mcp"]["url"]

方案 2：单工具包 MCP

适用于具有明确工具白名单的专用、范围受限的服务器：

const server = await composio.mcp.create("my-gmail-server", {
  toolkits: [{ authConfigId: "ac_xyz123", toolkit: "gmail" }],
  allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
});

const instance = await composio.mcp.generate("user-123", server.id);
console.log("MCP Server URL:", instance.url);

与 AI 提供商配合使用

from openai import OpenAI

client = OpenAI(api_key="your-openai-api-key")
mcp_server_url = "<https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?user_id=YOUR_USER_ID>"

response = client.responses.create(
    model="gpt-5",
    tools=[{
        "type": "mcp",
        "server_label": "composio-server",
        "server_url": mcp_server_url,
        "require_approval": "never",
    }],
    input="What are my latest emails?",
)

from anthropic import Anthropic

client = Anthropic(api_key="your-anthropic-api-key")
mcp_server_url = "<https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?user_id=YOUR_USER_ID>"

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What are my latest emails?"}],
    mcp_servers=[{
        "type": "url",
        "url": mcp_server_url,
        "name": "composio-mcp-server"
    }],
)

Composio 为你处理的事项

内置身份验证，支持 OAuth、API 密钥、JWT 和 Basic Auth

覆盖 Gmail、Slack、Notion、Linear、GitHub、Salesforce 等平台的 1000 多个托管集成

用于工具治理的 MCP Gateway。

20,000 多个预构建 API 操作，无需编码即可快速集成

MCP API 密钥强制验证（自 2026 年 3 月起，新组织默认启用）

用于以编程方式列出、更新和删除 MCP Server 的服务器管理 API

值得了解的局限性

平台支持并不均衡

Claude 以及 Cursor、Windsurf 等工具直接支持 MCP。但 ChatGPT 或本地模型可能无法开箱即用。支持范围正在扩大，但尚未普及到所有平台。

智能体自主性并不完善

MCP 赋予智能体使用工具的能力，但其判断能力仍在不断完善。工具使用效果取决于模型对工具描述和使用上下文的理解程度。

每次 MCP 工具调用都是外部调用，速度可能比 AI 直接根据训练数据回答更慢。如果按顺序编排多个工具，延迟会不断叠加。

目前大多数工具要么完全自主执行，要么完全不自主。最佳模式是：让 AI 先拟定操作，并在执行前请求确认。

可扩展性仍在演进

目前大多数 MCP Server 都是为单个用户构建的。这正是 MCP Gateway 发挥作用的地方：Composio 的网关架构提供集中式控制平面，用于大规模管理安全性、可观测性和运维复杂性。

安全性需要重视

MCP 的基础协议并未内置身份验证。Composio 通过 MCP API 密钥强制验证（自 2026 年 3 月起默认启用）、SOC2/ISO 认证、沙箱化执行和 RBAC 控制来解决这一问题。

Microsoft 的安全指南

自 2025 年初以来发生了哪些变化

从 npx 命令转向 SDK 优先的工作流。Composio SDK 允许你以编程方式创建和管理 MCP Server。

Tool Router 取代单独的服务器设置。通过单一端点，在 500 多个应用中动态发现工具。

面向企业的 MCP Gateway。用于身份验证、可观测性、速率限制和治理的集中式反向代理。

默认强制验证 API 密钥。弥补开放 MCP URL 带来的安全缺口。

支持更多框架。可直接集成 OpenAI、Anthropic、Mastra、AutoGen、LangChain 和 Claude Agent SDK。

Rube：一体化 MCP。单个服务器即可自动发现并选择合适的工具，同时保持 LLM 上下文简洁。

常见问题

Model Context Protocol 是一项开放标准，使 AI 智能体能够以一致的方式访问工具和数据。它将模型的思考过程与工具执行的操作分离开来。

Tool Router 和单工具包 MCP 有什么区别？

Tool Router 为你的智能体提供单一端点，可以动态访问所有工具包。单工具包 MCP 则为某个特定工具包创建专用服务器，并明确设置工具白名单。对于大多数使用场景，建议使用 Tool Router。

什么是 MCP Gateway？

它是位于 AI 智能体与工具之间的专用反向代理，提供集中式身份验证、可观测性、速率限制和治理能力。可以将其理解为 API Gateway，但它是专门针对 AI 智能体的通信模式构建的。

有哪些局限性？

不同平台的支持程度不一，智能体的判断能力并不完善，多工具链会累积性能开销；此外，在开放强大工具的访问权限时，你还需要管理好安全性和提示词卫生。