1.MCP

MCP 模型上下文协议：核心架构、三种落地形态与 Agent 实战手册

【核心主旨】：MCP (Model Context Protocol) 是大模型与外部系统交互的标准化“Type-C 接口”，通过统一规范让 AI 无缝调用本地工具与云端数据，彻底解决工具扩展的强耦合与安全隔离问题。

---

一、 MCP 核心概念与架构剖析

• 一句话结论：MCP 就是 AI 界的“统一接口转换器”，它把各种零散的工具和数据，打包成大模型开箱即用的标准能力。

1. 为什么需要它？（传统方案的致命痛点）

• 强耦合与重复造轮子：过去给大模型接工具，需要针对每个模型、每个框架手动写繁琐的 Function Calling 解析逻辑。换一个平台全套代码推翻重写，极难维护。
• 安全性差与密钥泄露：若直接把生产数据库密码写在 Agent 代码内部，一旦遭遇提示词注入攻击，核心数据和密钥将直接失窃。

2. 底层架构与角色分工

• 分工机制：
  • MCP Client（客户端）：位于用户侧的 AI 宿主软件（如 Claude 桌面端、Cursor、IDE 或自建 Agent 框架），负责大模型交互与工具调用指令的发起。
  • MCP Server（服务端）：独立运行的服务进程或云端接口，负责工具的具体执行、数据读取并将结果回传。从物理形态上，它可以清晰划分为三类：
    • 第一类（本地自研程序）：你自己写的服务端程序（如本地编写的 Python/Node 脚本），源码就在本地，由本地环境直接拉起运行。
    • 第二类（第三方公共包拉取）：别人写好的程序，发布在 uv/PyPI 或 npm/npx 等公共库中。通过命令自动将程序下载到本地缓存并在本地后台常驻运行。

      【核心共性】：前两类本质上都有具体的程序实体在你的本地电脑上常驻运行。

    • 第三类（远程云端服务）：本地没有任何运行文件。服务端程序部署在远程服务器上，本地仅配置了一个 HTTP 链接（URL）与鉴权 Token，直接通过网络跨机器连接到别人的服务端程序。
  • 大模型（LLM）：系统的思考大脑，根据客户端汇总的工具清单，自主决策调用哪个函数与入参。
• 流向链路： 大模型 (思考决策) ➡️ MCP Client (发起调用) ➡️ 传输通道 (Stdio/SSE) ➡️ MCP Server (物理执行) ➡️ 返回结果

---

二、 MCP 三种工程落地部署形态

• 一句话结论：不论工具来自哪里，使用端最终都只需要一份简明的 JSON 配置；背后根据运行位置与分发方式，严格分为三大落地形态。

1. 形态对比与技术特征清单

• 形态 1：本地自研源码直跑
  • 代码位置：保存在开发者本地硬盘上的源码文件（如 weather.py）。
  • 执行方式：通过本地 Python/Node 环境直接拉起执行（如 uv run weather.py），纯本地运行，不经过任何外部网络。
• 形态 2：公共生态包自动拉取（开箱即用）
  • 代码位置：托管在官方公共仓库（如 npm、PyPI）上的成熟开源包（如 @modelcontextprotocol/server-github、mcp-server-git）。
  • 执行方式：配置中指定 npx 或 uvx 命令。无需人工下载代码，运行时代理由包管理工具自动联网将程序下载至本地系统临时缓存区，并拉起常驻后台子进程。
• 形态 3：远程云端服务直连
  • 代码位置：服务部署在远端第三方服务器或企业内网集群上。
  • 执行方式：客户端配置远程 URL（如 https://api.example.com/sse）与鉴权 Token。本地电脑完全不下载任何文件、不拉起任何后端进程，纯走网络通信，真正的 MCP Server 运行在远端服务器上。

2. 底层进程创建机制解密（以 Stdio 配置为例）

{
  "command": "uv",
  "args": [
    "--directory", "/Users/joeygreen/PycharmProjects/weather",
    "run", "weather.py"
  ]
}

• 表面等价：相当于在终端执行 uv --directory /path run weather.py。
• 底层真实机制：
  • 客户端程序（如 Node.js 宿主）通过操作系统底层的进程创建接口（如 child_process.spawn）直接创建独立子进程。
  • 为什么拆分为 command 和 args 数组：避免通过 Shell 解析字符串，彻底规避因路径中含有空格而导致的转义解析崩溃，同时从物理层免疫 Shell 命令注入攻击。
  • 通道绑定：子进程拉起后分配独立 PID，客户端紧抓该进程的标准输入（stdin）和标准输出（stdout）管道，以 JSON-RPC 格式通过流式 I/O 进行通信。

---

三、 MCP 通信传输协议 (Transport)：Stdio 与 SSE 深度辨析

• 一句话结论：MCP 官方核心定义了“两大通信通道”；所谓 HTTP 与 SSE 本质是同一套网络通信方案的一体两面。

1. 协议核心差异与选型清单

• Stdio 协议（核心特征：MCP Server 运行在本地）：
  • 核心场景：只要 MCP Server 最终是在你本地电脑上运行，无论是你自己手写的 Python/Node 程序，还是通过 uvx / npx 自动把远端开源包拉取到本地运行，只要服务端程序在本地，均可且推荐使用 Stdio。
  • 底层本质：走操作系统的标准输入输出（stdin/stdout）控制台管道直接通信。完全不经过网络，不占用任何网络端口，零延迟、零网络开销且天然隔离。
• SSE 协议（核心特征：MCP Server 不在本地 / 纯网络通信）：
  • 核心场景：当对方没有提供任何本地可执行文件，而仅仅给了你一个 HTTP/HTTPS 网络链接（URL）和一个鉴权 Token 时，这种情况必须且只能使用 SSE。
  • 底层本质：因为 MCP Server 部署在远端服务器上，不在本地，必须走 HTTP 网络协议做跨机器通信。客户端发调用走 HTTP POST，远端服务端推流回传数据走 HTTP GET (SSE 长连接)。

2. 【核心细节与避坑指南】

• 细节 1（本地代码能否走 SSE 协议？）：
  • 完全可行！本地运行的 Python 文件可以通过 Web 框架（如 FastAPI/Starlette）绑定在本地端口（如 http://localhost:8000/sse）。
• 细节 2（本地 Stdio 与 本地 SSE 的场景抉择）：
  • 选择 Stdio：适合日常稳定使用。由 AI 客户端自动管理生命周期（随软件开闭自启停），不占端口，避免端口冲突。
  • 选择本地 SSE：适合深度开发调试（可在独立终端中查看实时 print 输出与报错，随时断点调试）以及多客户端共享（Cursor 与 Claude Desktop 可以同时连入同一个本地 8000 端口服务，共享内存状态）。

---

四、 LangChain / LangGraph 实战接入与工具白名单过滤

• 一句话结论：使用官方适配器可一行代码拉取 MCP 工具；在生产环境中必须配合白名单机制进行工具裁剪，降低 Token 开销并防止模型决策混乱。

1. 客户端多协议接入标准代码

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

async def main():
    # 1. 配置 MCP 客户端：同时聚合本地 Stdio 与 远程 SSE 服务
    client = MultiServerMCPClient({
        "local_weather": {
            "transport": "stdio",
            "command": "uv",
            "args": ["run", "weather.py"]
        },
        "remote_tools": {
            "transport": "sse",
            "url": "http://localhost:8000/sse"
        }
    })

    # 2. 全量拉取 MCP 声明的工具列表
    all_tools = await client.get_tools()

    # 3. 工具白名单过滤（按需裁剪，规避上下文过载）
    needed_names = ["get_current_weather", "get_forecast"]
    selected_tools = [t for t in all_tools if t.name in needed_names]

    # 4. 接入 LangGraph 构建自主 Agent
    model = ChatOpenAI(model="gpt-4o")
    agent = create_react_agent(model, selected_tools)

    # 5. 执行调用
    result = await agent.ainvoke({"messages": [("user", "北京天气如何？")]})
    print(result["messages"][-1].content)

if __name__ == "__main__":
    asyncio.run(main())

【代码解析】：通过 MultiServerMCPClient 实现多源服务聚合，client.get_tools() 拿到的均为标准 Python 工具对象，利用列表推导式根据 .name 属性做白名单过滤，实现极简解耦。

2. 【核心细节与避坑指南】

• 避坑指南（渐进式披露与工具过载惩罚）：
  • 单个 MCP Server 往往提供数十个细粒度工具，如果无脑全部注入 Agent 上下文，会导致大模型 Prompt 长度剧增、Token 成本飙升，并引发模型在相似工具间犹豫不决甚至幻觉调用。
  • 生产规范应当在 Agent 层建立按需暴露的白名单，或通过路由层进行分层按需挂载。

---

五、 全局大串联 (终极总结)

1. 全链路协同思维链条

明确工具需求 ➡️ 选定部署形态 (本地自研 / 公共包 / 远程云端) ➡️ 匹配通信协议 (Stdio 管道 / SSE 网络流) ➡️ 框架客户端聚合拉取 ➡️ 白名单过滤裁剪 ➡️ Agent 注入闭环执行

2. 【终极一句话速记】

“自研代码本地管，公共工具包代跑，远端云服纯走网；日常生产用 Stdio 随启随停无端口，联调排错起本地 SSE 终端看流；全量拉取莫盲目，白名单过滤省 Token 防迷糊。”