伙伴赋能站WorkBuddy ✓ 授权证书
首页 / 进阶手册 / MCP协议与标准化

MCP协议与标准化 · 进阶手册

MCP 原理、与函数调用的区别、连接器使用。

中科光华(成都)数字科技有限公司 腾讯云 WorkBuddy 授权伙伴

为什么这一块很重要

如果你正在使用WorkBuddy,你一定遇到过这样的场景——你让AI帮你整理腾讯文档里的会议纪要,它回复"我无法访问外部文件";你让AI帮你查一下最近的邮件,它只能给你一个邮件模板,而不能真的去收件箱里取;你让AI帮你从数据库里拉一份报表,它说"我没有连接数据库的能力"。这就是AI的"孤岛困境":模型本身非常聪明,但它被锁在一个封闭的沙盒里,无法触碰你真实工作中的数据、工具和服务。每一次你想要AI处理真实数据,都要经历"手动搬运→粘贴→AI处理→复制结果→手动回写"的繁琐流程。这个"搬数据"的环节,很多时候比AI处理本身还费时间。MCP(Model Context Protocol,模型上下文协议)正是解决这个问题的核心标准。 它是Anthropic于2024年11月推出的开放标准协议,旨在为AI模型与外部数据源、工具之间构建统一的交互接口。如果说AI模型是"大脑",那么MCP就是让大脑能够伸出手去操作外部世界的"神经系统"——它让AI从"只能思考"进化为"能够行动"。在WorkBuddy中,MCP协议以连接器(Connector)的形式落地。通过连接器,WorkBuddy可以直接读写你的腾讯文档、QQ邮箱、腾讯乐享知识库,甚至通过自定义MCP服务器接入企业内部API、数据库和任意第三方服务。理解MCP协议,意味着你能够:高效连接外部工具:知道为什么内置连接器"即插即用",而自定义连接器需要配置MCP服务器;扩展能力边界:知道什么时候该用连接器,什么时候该用技能(Skills),避免"用锤子拧螺丝";排查连接故障:知道MCP的Client-Server架构中,问题出在哪一层,该怎么修;把握未来趋势:知道MCP协议正在从"有状态"走向"无状态",从"开发者工具"走向"企业基础设施",提前布局。2026年7月28日,Anthropic发布了MCP第五版规范(代号2026-07-28),这是该协议自2024年11月推出以来规模最大、最系统性的重构——从有状态会话全面转向无状态架构。MCP周SDK下载量已突破2.5亿次,28%的财富500强企业已在生产环境中部署MCP服务器,金融科技领域渗透率高达45%【来源:钛媒体《Anthropic的HTTP时刻:MCP第五版全面无状态化》,2026年7月】。这不是一个"了解一下就行"的技术,而是"必须掌握"的AI基础设施。

核心概念

概念一:MCP协议设计原理——Client-Server架构、Transport层、能力发现

1.1 协议定位与分层设计MCP(Model Context Protocol)专注于上下文交换的协议层,它不规定AI应用如何使用LLM或管理所提供的上下文。这一设计哲学使得MCP可以与任何LLM配合使用,而不绑定于特定模型提供商。MCP由两层构成:数据层(Data Layer):定义基于JSON-RPC 2.0的客户端-服务器通信协议,包括能力与版本发现、核心原语(Tools、Resources、Prompts、Notifications)。数据层是协议的"内层",定义了"说什么"。传输层(Transport Layer):定义通信机制与通道,包括连接建立、消息分帧、授权。传输层是协议的"外层",定义了"怎么说"。传输层将通信细节从协议层抽象出来,使相同的JSON-RPC 2.0消息格式可跨所有传输机制使用。这意味着无论你使用本地stdio通信还是远程HTTP通信,上层协议逻辑完全一致。示例:当WorkBuddy通过MCP连接QQ邮箱时,无论底层是本地stdio还是远程HTTP,QQ邮箱的MCP服务器暴露的"搜索邮件""发送邮件"等工具接口完全一致,区别仅在于传输通道不同。1.2 Client-Server架构MCP遵循客户端-服务器架构,核心参与者包括:

角色
说明
示例
MCP Host(宿
主)
AI应用,协调并管理一个或多个MCP客户端
WorkBuddy、Claude Desktop、VS
Code、Cursor
MCP Client(客
户端)
由Host为每个Server创建,维护专用连接,
从Server获取上下文供Host使用
WorkBuddy内部为每个连接器创建的客
户端实例
MCP Server
(服务器)
提供上下文的程序,暴露特定功能(工具、资
源、提示词)并访问数据源
QQ邮箱MCP服务器、腾讯文档MCP服务
器、自定义MCP服务器

连接模型:Host为每个连接的Server实例化一个Client。例如,WorkBuddy同时连接腾讯文档Server和QQ邮箱Server时,会创建两个独立的Client实例,分别维护各自的连接。部署形态:- 本地Server(STDIO传输):通常服务单个Client,运行在同一台机器上,通过标准输入/输出流通信。- 远程Server(Streamable HTTP传输):通常服务多个Client,运行在云端,通过HTTP协议通信。示例:WorkBuddy内置的QQ邮箱连接器是一个远程MCPServer,通过OAuth2.1授权,使用StreamableHTTP传输。而你在本地用Python编写的自定义MCPServer,则使用STDIO传输,WorkBuddy通过启动本地进程与之通信。1.3 Transport层详解传输层管理信道与认证,支持两种机制:

传输机制
说明
适用场景
Stdio Transport
使用标准输入/输出流,同机进程间直接通信,无网络开销,性
能最优
本地自定义MCP服
务器、开发调试
Streamable HTTP
Transport
使用HTTP POST发客户端消息,可选SSE流式;支持标准HTTP
认证(Bearer Tokens、API Keys、自定义头),推荐OAuth获
取令牌
远程MCP服务器、
团队共享、生产部
署

关键演进:MCP第五版(2026-07-28)将Streamable HTTP传输从"有状态会话"升级为"无状态"。旧版本中,每次远程MCP交互都需要一个Session ID(Mcp-Session-Id头),将客户端固定在最初创建会话的服务器实例上,这意味着部署MCP服务器需要粘性会话(Sticky Session)、共享会话存储和深度包检测。新版本中,任何一个MCP请求都可以被任何服务器实例处理,一个普通的轮询负载均衡器就够了【来源:钛媒体《Anthropic的HTTP时刻》,2026年7月】。1.4 能力发现机制(Discovery)MCP是无状态协议(第五版起),每个请求都在_meta 字段中携带协议版本和相关能力。服务器通过强制的server/discover 请求公布支持的版本与能力。发现请求:客户端可发server/discover ,包含:- io.modelcontextprotocol/protocolVersion :客户端所用版本- io.modelcontextprotocol/clientInfo :客户端名与版本- io.modelcontextprotocol/clientCapabilities :如elicitation (请求用户信息)发现响应:含服务器支持的supportedVersions 、自身serverInfo 与serverCapabilities (如tools:{listChanged: true} 、resources: {} )。作用:- 版本选择:若服务器不支持请求版本,返UnsupportedProtocolVersionError ,客户端重试- 能力发现:双方知晓对方可处理的原语与通知支持- 身份交换:供调试与兼容示例:当WorkBuddy连接腾讯文档MCP服务器时,首先通过server/discover 获知该服务器支持哪些工具(如"读取文档""创建文档""编辑文档")和哪些资源(如"文档列表"),然后根据用户需求选择合适的工具调用。1.5 核心原语(Primitives)MCP定义了三类服务器端核心原语和三类客户端原语:服务器端原语:

原语
说明
示例
Tools(工具)
可执行函数,模型可调用以执行操作
发送邮件、创建文档、查询数据库
Resources(资源)
上下文数据源,模型可读取以获取信息
文件内容、数据库记录、邮件列表
Prompts(提示词)
可复用模板,标准化LLM交互流程
邮件回复模板、报告生成模板

客户端原语(第五版新增或强化):

原语
说明
Elicitation
请求用户信息(如URL模式、表单模式)
Sampling
请求LLM补全(注:第五版已废弃,12个月弃用期内仍可使用)
Logging
发送日志

示例:QQ邮箱MCP服务器暴露的"搜索邮件"是一个Tool,"最近邮件列表"是一个Resource,"正式邮件回复模板"是一个Prompt。WorkBuddy通过能力发现机制知道这些原语的存在,然后根据用户意图选择调用。

概念二:MCP与Function Calling对比——适用场景、优劣分析

这是理解MCP协议时最核心也最容易被混淆的概念。很多用户认为MCP就是"另一种API调用方式",实际上MCP和Function Calling解决的是不同层面的问题。2.1 工作原理对比Function Calling(函数调用)——Phase 1:意图生成FunctionCalling是LLM的API级功能。开发者用JSONSchema定义工具(name、description、parameters),通过API的tools 参数发给模型。当LLM决定需要外部数据或操作时,返回结构化JSON(指定函数名与参数)。模型本身不执行函数,应用读取JSON、本地执行代码、将结果回传模型。MCP(模型上下文协议)——Phase 2:执行基础设施标准化MCP是基于JSON-RPC 2.0的开放客户端-服务器标准,定义工具如何跨应用/LLM提供商被发现、调用和管理。工具逻辑移出应用,由独立MCP Server暴露。AI客户端(如WorkBuddy)连接MCP服务器后自动发现其工具,客户端处理工具调用的完整生命周期——应用代码无需管理API往返。关键结论:MCP不替代函数调用。函数调用是模型"表达想做什么",MCP是让请求"可移植、可发现、可执行"的基础设施。在底层,MCP客户端实际上将服务器工具转换为函数调用与模型通信【来源:Portkey Blog《MCP vs Function Calling – How They Actually Work Together》,2026年3月】。2.2 全面对比表

维度
Function Calling
MCP
工具存放
位置
在API请求中以内联JSON Schema定义
在独立的外部服务器进程中,打包并单独分发
谁编写工
具逻辑
应用开发者,包含在API调用中
MCP服务器作者,打包并单独分发
可复用性
低——工具与特定应用紧耦合
高——任何支持MCP的AI客户端可使用同一服
务器
设置要求
在每次API请求中定义工具Schema;无需单独
进程
安装并运行MCP服务器;配置AI客户端
认证方式
由调用API的应用处理
由服务器进程处理(环境变量、OAuth等)
工具发现
每次请求手动指定
运行时自动发现(tools/list 、server/
discover )
新增工具
需修改代码重新部署
服务器增删工具后发通知自动更新,无需改代
码
跨提供商
兼容
差——OpenAI、Anthropic、Gemini、Llama
四家格式互不兼容
好——统一tools/call JSON-RPC方法,与底
层LLM无关
凭证隔离
差——所有凭证存于应用环境,全有或全无
好——凭证隔离在Server级,单Server被攻破
仅泄露该Server凭证
延迟
最低——全进程内执行
有额外hop——本地stdio有进程跳,远程HTTP
有网络跳
最佳场景
SaaS产品、嵌入式AI功能、单应用工具
桌面应用、开发者工具、Agent工作流、共享
集成

2.3 适用场景决策

因素
用Function Calling
用MCP
两者混合
工具数量
< 5个
10+
10+且复杂度混合
LLM提供商
单一
多提供商
多提供商
消费团队
一个应用
多团队
多团队
设置复杂度
轻量(约20行代码)
独立服务器+协议
分层架构
延迟敏感度
极高(进程内执行)
可接受
MCP处理大部分工具,热路径用直接调用
合规需求
低
需凭证隔离
需治理层

在WorkBuddy中的体现:WorkBuddy内部同时使用了Function Calling和MCP两种机制。当你使用内置技能(Skills)时,本质上是Function Calling——工具逻辑内嵌在WorkBuddy应用中。当你使用连接器(Connector)时,本质上是MCP——工具逻辑在独立的MCP服务器中,WorkBuddy通过MCP协议与之通信。2.4 为什么MCP被称为"AI的USB-C"在MCP出现之前,存在M×N连接困境:每个AI模型连接每个外部工具都需要一条点对点集成。10个AI模型乘以10个数据源,等于100条自定义集成。MCP用N+M的方式解决了这个问题:每个AI应用实现一次客户端协议,每个工具实现一次服务器协议,然后一切互通【来源:钛媒体《Anthropic的HTTP时刻》,2026年7月】。这就像USB-C统一了充电接口——在此之前,每个手机厂商用不同的充电口;USB-C出现后,一根线充所有设备。MCP统一了AI工具接口——在此之前,每个AI应用和每个工具之间需要定制集成;MCP出现后,一个协议连所有工具。

概念三:WorkBuddy内置连接器——QQ邮箱、腾讯文档、腾讯地图、有道云笔记

3.1 连接器的本质连接器是WorkBuddy与外部服务之间的桥梁,将外部能力引入AI工作流。技术形态分为:MCP + CLI(标准化协议):通过MCP协议与外部MCP服务器通信,支持OAuth授权、能力发现、实时通知等完整MCP特性。内置连接器(腾讯文档、QQ邮箱等)和自定义MCP连接器均属于此类。Skill + CLI(内置脚本):通过内置脚本直接调用外部API,不走MCP协议,适用于简单、固定的集成场景。二者在数据收集和权限边界上遵循一致原则。3.2 内置连接器列表与功能

连接器
能做什么
授权方式
技术形态
腾讯文档
读取、创建、编辑云端Word/Excel/PPT
微信/QQ/企业微信扫码
MCP + CLI
QQ邮箱
搜索邮件、整理邮件、起草回复、发送邮件
QQ邮箱App扫码授权
MCP + CLI
腾讯乐享
搜索、创建和管理乐享知识库中的文档
微信/手机号/企业微信登录
MCP + CLI
腾讯地图
地理位置查询、路线规划、POI搜索
API Key
MCP + CLI
有道云笔记
读取、搜索和整理云笔记内容
OAuth授权
MCP + CLI

QQ邮箱连接器详细配置流程:添加连接器:在WorkBuddy连接器管理页面找到QQ邮箱卡片,点击右侧"+"按钮扫码授权:系统跳转到QQ邮箱授权页面,使用QQ邮箱App(7.1.5/鸿蒙0.2.9及更新版本)扫码确认权限:手机端确认WorkBuddy申请的访问权限,包括:- 账号信息:获取邮箱账号基础信息- 读取邮件:读取收件箱内近一个月的邮件- 发送邮件:代为发送邮件- 删除邮件(可选):已删除邮件会移入"已删除"文件夹授权成功:手机端显示"授权成功"连接完成:WorkBuddy中QQ邮箱卡片名称旁出现绿色圆点腾讯文档连接器使用示例:3.3 连接器的权限边界WorkBuddy连接器遵循严格的权限边界原则:每个连接器独立授权:不同服务的授权互不影响不主动定时抓取:只在用户指令触发时按需读取数据不超出已有权限范围:连接器以用户本人身份、在用户已有的权限范围内执行。用户在腾讯文档里看不到的文件,连接器同样看不到积分消耗规则:连接器自身的读写不消耗积分;WorkBuddy对外部数据进行理解、汇总时会消耗积分【来源:腾讯云文档《WorkBuddy Enterprise 连接器》,2026年】

概念四:自定义MCP服务器——配置方法、常见服务端推荐

4.1 为什么需要自定义MCP服务器内置连接器覆盖了最常见的办公场景,但企业用户的真实需求远不止于此。你可能需要:连接企业内部API(如CRM系统、ERP系统、自研平台)连接非内置支持的第三方服务(如Notion、GitHub、Slack)连接数据库(如PostgreSQL、MySQL、MongoDB)连接文件系统或其他本地资源自定义MCP服务器就是为此而生——你可以将任何外部服务封装为MCP服务器,让WorkBuddy通过MCP协议与之交互。4.2 MCP运行时依赖在安装WorkBuddy客户端(≥ v4.21)后,自定义连接器需要确保本地环境具备:Python(推荐Python 3.10+):需安装fastmcp 、mcp 包Node.js(如用Node实现):需安装@modelcontextprotocol/sdkuv(Python包管理器):通过pip install uv 安装验证安装:4.3 Python FastMCP实现(推荐)Step 1:创建MCP Server创建knowledge_server.py ,使用@mcp.tool() 装饰器定义工具函数。必须写清docstring——AI依赖其理解工具用途。⚠ 关键注意:若参数无类型注解和docstring,会导致工具参数解析失败。这是自定义MCP服务器最常见的错误之一。Step 2:在WorkBuddy中配置连接器编辑配置文件~/.workbuddy/mcp.json (用户级)或<项目目录>/.workbuddy/mcp.json (项目级):Step 3:验证连接WorkBuddy侧边栏 → 插件 → MCP服务器,查看状态:- ✅ 绿色 = 连接成功- ✅ 红色 = 配置异常(检查Python路径和Token)4.4 Node.js实现使用@modelcontextprotocol/sdk 编写knowledge_server.js :在mcp.json 中配置:4.5 远程SSE部署(生产推荐)适用于团队共享,部署到云服务器后通过SSE接入,无需每个用户本地安装。服务器端:WorkBuddy配置:4.6 常见MCP服务器推荐

服务端
功能
安装方式
来源
@modelcontextprotocol/server-filesystem
本地文件系统访问
npm install -g
官方
@modelcontextprotocol/server-github
GitHub仓库操作
npm install -g
官方
@modelcontextprotocol/server-postgres
PostgreSQL数据库查询
npx
官方
@modelcontextprotocol/server-slack
Slack消息管理
npm install -g
官方
mcp-server-notion
Notion笔记操作
pip install
社区
mcp-server-mysql
MySQL数据库查询
pip install
社区

【来源:MCP官方文档、MCPCMD社区目录】4.7 内置与自定义连接器对比

维度
内置连接器
自定义MCP连接器
服务
腾讯文档、QQ邮箱、腾讯乐享、腾讯地图、有
道云笔记等
企业微信机器人、钉钉机器人、自建API、
GitHub、Notion等
授权方
式
微信/QQ/企业微信扫码或登录
Webhook/API Key/Token
配置难
度
极低——扫码即用
中等——需编写或安装MCP服务器
适用场
景
日常办公自动化
企业内部系统集成、特殊需求
维护责
任
WorkBuddy官方维护
用户自行维护
安全审
核
已通过官方审核
需自行审计(建议用skills-security-check 技
能)

关键原则:内置够用先用内置;自定义MCP写好docstring;安全第一,Token永不明文。

概念五:MCP生态标准——协议版本、兼容性、未来发展方向

5.1 协议版本演进MCP自2024年11月推出以来,经历了多次重大版本迭代:

时间
版本/事件
核心变化
2024-11
MCP首次开源
初始版本,解决M×N连接困境,stdio传输,有状态会话
2025-03
第二版规范
引入Streamable HTTP与OAuth 2.1;OpenAI宣布全面支持(拐点)
2025-04
Google支持
Google DeepMind确认支持Gemini
2025-06
OAuth强化
规范将MCP服务器定为OAuth资源服务器,强制Resource Indicators(RFC
8707)
2025-09
MCP Registry
上线
公共注册表启动,数月内增至近2,000个服务器条目
2025-11
2025-11-25规
范
异步任务、增强采样、Elicitation、服务端Agent循环、CIMD、客户端安全要
求、扩展系统
2025-12
捐赠至AAIF
Anthropic将MCP捐赠给Linux基金会旗下的Agentic AI Foundation,OpenAI
与Block为联合创始
2026-01
MCP Apps
较早的官方扩展发布(支持交互式UI,与OpenAI共建)
2026-03
2026路线图发
布
企业就绪为顶级优先级
2026-07-28
第五版规范
全面无状态化——移除Initialize/Initialized握手、移除Mcp-Session-Id头;新
增server/discover;版本化扩展框架;MCP Apps和Tasks扩展毕业;废弃
Roots、Sampling、Logging

【来源:WorkOS Blog《Everything your team needs to know about MCP in 2026》,2026年3月;钛媒体《Anthropic的HTTP时刻》,2026年7月】5.2 生态规模截至2026年7月,MCP生态已呈现爆发式增长:MCP服务器数量:公共注册表索引约20,000个MCP服务器【来源:Safeguard.sh《Model ContextProtocol in 2026》,2026年7月】SDK下载量:周SDK下载量突破2.5亿次【来源:钛媒体《Anthropic的HTTP时刻》,2026年7月】企业采用:28%的财富500强企业已在生产环境中部署MCP服务器,金融科技领域渗透率高达45%【来源:同上】主要客户端:Claude、ChatGPT、Gemini、Microsoft Copilot、GitHub Copilot、Cursor、Windsurf、VS Code、Zed等均已支持MCP主要服务器:Slack、GitHub、Google、Salesforce、Stripe、HubSpot、Shopify、Notion、Linear、Sentry、Figma等已构建官方或社区维护的服务器服务器类型分布:API类35%、数据库类28%、文件系统类18%、其他垂直场景19%【来源:掘金《MCP生态爆发》,2026年5月数据】5.3 治理与标准化从Anthropic的协议到行业标准:2025年12月,Anthropic将MCP捐赠给Linux基金会旗下的AgenticAIFoundation(AAIF),由Anthropic、Block和OpenAI联合创立,AWS、Google、Microsoft、Cloudflare、GitHub和Bloomberg作为支持成员。MCP从此不再是Anthropic的独有项目,而是由社区驱动的开放标准。治理机制:- SEP(Specification Enhancement Proposals):协议变更通过SEP提案推动,社区评审- 工作组:Transports、Auth、Registry等工作组负责各领域标准化- 兴趣组:面向特定领域(如企业安全、多租户)的兴趣组MCP首席维护者David Soria Parra透露:微软和谷歌实际上是MCP v5许多变化的"最大推动者",这本身就是MCP作为开放标准成功的标志【来源:钛媒体《Anthropic的HTTP时刻》,2026年7月】。5.4 安全现状MCP已脱离"理论攻击"阶段,拥有实际严重漏洞记录:CVE-2025-49596(CVSS 9.4):Anthropic的MCP Inspector开发者工具localhost代理无认证,恶意网页可通过CSRF式请求实现远程代码执行,已于0.14.1修复CVE-2025-6514(CVSS 9.6):广泛使用的mcp-remote代理(npm下载数十万次)在连接恶意MCP服务器时可被驱使执行任意OS命令,0.1.16(2025年6月17日)修复2026年4月,OX Security披露RCE漏洞影响超1.5亿下载2026年6月,NSA发布针对基于MCP自动化的安全设计考虑主要安全风险:1. 混淆副手问题(Confused Deputy):提示注入可诱使Agent以攻击者参数调用合法工具2. 服务器自身漏洞:本地AI工具的开发者尤其容易受攻击3. 供应链暴露:MCP服务器以npm/PyPI包分发,存在typosquatting或后门风险4. 新增威胁:随着类应用HTML界面、长时任务引入,存储型XSS、资源耗尽DoS等进入威胁模型【来源:Safeguard.sh《Model Context Protocol in 2026》,2026年7月】5.5 未来发展方向2026年路线图四大优先领域:传输演进:Streamable HTTP向无状态多实例扩展;会话创建/恢复/迁移;标准化MCP ServerCards(通过.well-known URL暴露元数据以便发现)Agent通信:基于采样、服务端循环、并行调用,扩展多步推理与协调模式企业就绪:- 结构化审计追踪与可观测性(接入SIEM/APM)- 企业管理的SSO集成认证- 网关/代理模式(授权传播、会话亲和)- 跨客户端配置可移植性治理成熟:明确贡献者阶梯、工作组授权、标准章程模板AAIF新项目:- Agent Gateway:为MCP流量管理提供统一的策略执行层- Agentic Commerce:让MCP充当商品和服务的发现层,允许商家向AI Agent曝光产品和服务【来源:WorkOS Blog《Everything your team needs to know about MCP in 2026》,2026年3月】5.6 第五版Breaking Changes的影响MCP v5包含Breaking Changes,现有服务器和客户端需要迁移:Roots、Sampling、Logging被废弃:根据12个月弃用政策,这些功能在当前版本及未来一年内仍可使用,但不再推荐新实现使用Sampling的废弃影响最大:Sampling允许MCP服务器通过客户端反向调用LLM,废弃意味着重建信任边界——服务器现在需要直接调用模型提供商的API,这改变了网络架构、认证模型和成本归属方式Initialize/Initialized握手被移除:替换为_meta 字段携带+ server/discover 按需发现对于WorkBuddy用户而言,这意味着:未来升级WorkBuddy版本时,自定义MCP服务器可能需要相应更新以兼容新协议。建议关注WorkBuddy官方的升级公告。

实操方法

方法一:如何为WorkBuddy配置自定义MCP服务器

场景你的团队有一个内部知识库API( ),你希望WorkBuddy能够直接查询和操作这个知识库,而不是每次都手动复制粘贴。步骤第一步:环境准备第二步:编写MCP服务器创建文件~/mcp-servers/knowledge_server.py :第三步:本地测试如果服务器正常启动且无报错,说明服务器代码本身没问题。第四步:配置WorkBuddy连接编辑~/.workbuddy/mcp.json :⚠ 重要:args 中的路径必须使用绝对路径,不要使用相对路径或~ 。第五步:验证连接重启WorkBuddy客户端在侧边栏 → 连接器 → MCP服务器,查看状态✅ 绿色 = 连接成功✅ 红色 = 配置异常,检查:- Python路径是否正确(which python 获取绝对路径)- Token是否有效- 脚本文件是否有执行权限第六步:在对话中使用WorkBuddy会自动识别你接入了企业知识库MCP服务器,调用search_docs 工具查询并返回结果。安全注意事项Token永不明文写在配置文件中:应使用环境变量引用,如"KNOWLEDGE_API_TOKEN": "$

{KNOWLEDGE_API_TOKEN}"

安装第三方连接器前,用skills-security-check 技能审计:检查危险命令、数据外泄等,风险等级P0拒绝安装自定义连接器的访问范围由你的配置决定:WorkBuddy不预设范围,请审慎评估后再启用

方法二:如何选择MCP连接器 vs Skills技能解决特定问题

判断原则WorkBuddy提供了两种扩展能力的方式:连接器(Connector)和技能(Skill)。选择错误会导致效率低下甚至无法完成任务。

判断维度
用连接器(MCP)
用技能(Skills)
数据来源
需要访问外部服务中的实时数据(邮件、文档、数据库)
只需要AI处理已有信息或执行通用任
务
操作类型
需要对外部服务执行写操作(发邮件、创建文档、更新数
据库)
只需要生成内容(写文案、翻译、总
结)
数据时效
性
需要最新数据(实时邮件、实时库存)
可用静态数据或AI自身知识
交互频率
需要频繁与外部系统交互
一次性任务
多团队复
用
同一集成需要多个团队使用
任务特定于个人或单次使用
凭证需求
需要独立的认证和权限隔离
不涉及外部凭证

典型场景决策场景1:整理会议纪要- 你已经在WorkBuddy中粘贴了会议纪要文本 → 用Skills(总结、提取待办事项)- 会议纪要在腾讯文档中 → 用连接器(先读取文档,再处理)场景2:回复邮件- 你只需要AI帮你写一封邮件草稿 → 用Skills(文案生成)- 你需要AI直接读取邮件、起草回复并发送 → 用连接器(QQ邮箱连接器)场景3:查询数据库- 你只需要AI帮你写一条SQL → 用Skills(代码生成)- 你需要AI直接查询数据库并返回结果 → 用连接器(自定义MCP数据库连接器)场景4:生成周报- 你手动提供工作内容 → 用Skills(格式化、总结)- 工作内容散落在腾讯文档、邮件、TAPD中 → 用连接器(多源数据聚合)混合策略在实际工作中,最高效的方式往往是连接器+技能混合使用:用连接器从多个外部源拉取数据用技能对数据进行深度处理和分析用连接器将结果写回外部系统示例:

方法三:如何排查MCP连接器故障

MCP连接器故障排查需要理解MCP的Client-Server架构,定位问题出在哪一层。故障排查流程图常见故障及解决方案故障1:连接器授权后AI"找不到"文件原因:腾讯文档权限问题,AI只能访问你有权限的文件解决:确认目标文件在你的个人空间或有明确共享权限,不在别人的私有空间里故障2:邮件连接后AI读取很慢原因:邮件数量太多,AI在全量扫描解决:描述需求时加上时间范围和关键词限定,如"最近3天来自'@163.com'的邮件中,标题包含'合同'或'审批'的邮件列表"故障3:自定义MCP服务器参数解析失败原因:工具函数缺少类型注解或docstring解决:务必为每个参数添加类型注解,为每个工具函数写清docstring故障4:远程SSE连接器偶尔断开原因:网络波动或Token过期解决:检查网络稳定性;确认OAuth Token的Refresh Token是否有效;考虑使用本地stdio传输替代远程SSE故障5:自动化任务没有如期执行原因:WorkBuddy客户端被关闭了解决:自动化任务需要客户端保持运行。建议在公司电脑上设置"开机自启",或者把定时任务安排在工作时间内

常见误区

误区一:MCP = API调用

误区描述:很多用户认为MCP不过是"另一种API调用方式",和直接调用REST API没什么区别。实际:MCP是标准化协议,不是简单的API调用。核心区别在于:

维度
API调用
MCP协议
能力发现
需要手动查阅文档,硬编码API
端点
运行时自动发现(server/discover 、tools/list )
协商机制
无——客户端必须知道服务器
支持什么
有——双方交换协议版本和能力,自动协商
工具变更
服务器API变更后,客户端必须
手动更新
服务器增删工具后发notifications/tools/list_changed 通知,
客户端自动更新
跨应用复
用
每个应用需要单独实现API集成
同一MCP服务器可被任何MCP兼容客户端使用
认证标准
化
每个API有自己的认证方式
统一OAuth 2.1 + PKCE标准

纠正方法:当你想到MCP时,不要把它类比为"API调用",而应该类比为"USB-C接口"——USB-C不只是"一种充电方式",它是一个包含能力协商、功率检测、数据传输协议的完整标准。MCP同样不只是"一种调用工具的方式",它是一个包含能力发现、版本协商、认证标准化、实时通知的完整协议。

误区二:所有外部工具都需要MCP

误区描述:有些用户认为,只要需要连接外部服务,就必须用MCP连接器,否则无法实现。实际:简单任务用Skills就够了。MCP连接器适合需要实时数据访问和双向操作的场景,而Skills适合内容生成和信息处理的场景。典型错误案例:

场景
错误做法
正确做法
翻译一段文本
配置翻译API的MCP服务器
直接用Skills翻译
写一封邮件草稿
配置邮件MCP服务器
用Skills写草稿,手动复制发送
查询实时库存
用Skills让AI"估算"
用MCP连接器直接查询数据库
整理会议纪要(已粘贴)
用MCP连接器读取
用Skills直接处理已有文本

纠正方法:使用"进出判断法"——如果任务需要AI从外部系统读取数据(进)或向外部系统写入数据(出),用连接器;如果任务只需要AI处理已有信息,用技能。

误区三:MCP配置很复杂

误区描述:很多用户一听到"协议""服务器""配置"就觉得门槛很高,不敢尝试。实际:内置连接器OAuth即用——点击添加、扫码授权、绿色圆点确认,三步完成。自定义MCP服务器的配置虽然比内置连接器复杂一些,但核心就是编写一个Python脚本+编辑一个JSON配置文件,不需要任何网络或运维知识。内置连接器配置流程(以腾讯文档为例):点击添加 → 2. 扫码授权 → 3. 绿色圆点确认自定义MCP服务器配置流程:编写Python脚本(约20-30行核心代码) → 2. 编辑mcp.json(约10行配置) → 3. 重启WorkBuddy纠正方法:不要被"协议"这个词吓到。MCP的设计初衷就是让AI工具连接像"USB-C即插即用"一样简单。内置连接器已经做到了"扫码即用"的体验,自定义连接器也只需要写一个简单的Python脚本。从最简单的内置连接器开始尝试,逐步扩展到自定义连接器。

误区四:MCP连接器会自动定时抓取我的数据

误区描述:有些用户担心连接器授权后,WorkBuddy会持续监控和抓取外部服务中的数据。实际:WorkBuddy连接器遵循最小必要原则:- 不主动定时抓取:只在用户指令触发时按需读取数据- 不超出已有权限范围:连接器以你本人身份、在你已有的权限范围内执行- 每个连接器独立授权:不同服务的授权互不影响- 可随时禁用:在连接器管理页面点击开关即可禁用纠正方法:理解连接器的权限边界——它本质上是一个"代理",以你的身份执行你明确要求的操作。它不会"偷偷"做任何事,就像你不会担心你的浏览器"偷偷"访问网站一样。

误区五:MCP和Function Calling是竞争关系,选了MCP就不能用Function Calling

误区描述:有些用户认为MCP和Function Calling是两种互斥的技术路线,必须二选一。实际:MCP和Function Calling解决的是不同层面的问题,互补而非二选一。Function Calling是模型"表达想做什么"(意图生成),MCP是让请求"可移植、可发现、可执行"(执行基础设施标准化)。在底层,MCP客户端实际上将服务器工具转换为函数调用与模型通信。多数成熟生产系统采用混合模式:函数调用处理对话内模型工具请求,MCP管理基础设施层路由与执行。在WorkBuddy中,Skills(基于Function Calling)和连接器(基于MCP)就是混合使用的典型例子。纠正方法:不要把MCP和Function Calling看作"A/B选择",而应该看作"分工协作"。用Function Calling处理简单、单应用内的工具调用;用MCP处理复杂、跨应用、需要凭证隔离的集成场景。两者在WorkBuddy中已经无缝融合,你只需要根据场景选择合适的工具。

实操模板/检查清单

模板一:MCP连接器选择决策表

评估维度
你的情况
建议选择
1. 是否需要访问外部实时数据?
□ 是 □
否
是→连接器;否→继续评估
2. 是否需要对外部系统执行写操作?
□ 是 □
否
是→连接器;否→继续评估
3. 数据是否在WorkBuddy内置连接器支持的服务
中?
□ 是 □
否
是→内置连接器;否→自定义MCP
4. 是否需要多团队复用同一集成?
□ 是 □
否
是→MCP(远程SSE部署);否→继续评
估
5. 是否需要凭证隔离和合规审计?
□ 是 □
否
是→MCP;否→Skills可能够用
6. 工具数量是否超过10个?
□ 是 □
否
是→MCP更优;否→Skills可能够用
7. 是否需要跨LLM提供商使用?
□ 是 □
否
是→MCP;否→Function Calling可能够
用

决策路径:- 如果1和2都为"否" → 使用Skills- 如果1或2为"是",且3为"是" → 使用内置连接器- 如果1或2为"是",且3为"否" → 使用自定义MCP连接器- 如果4或5为"是" → 使用MCP(远程SSE部署)

模板二:自定义MCP服务器配置模板

Python服务器脚本模板:远程SSE部署配置模板:Node.js服务器脚本模板:

模板三:连接器故障排查清单

A. 连接失败排查清单(状态显示红色)

序
号
检查项
检查方法
通过标准
MCP服务器脚本是否可运行
在终端手动执行:python /path/to/
server.py
无报错,正常启动
Python/Node.js路径是否正确
终端执行:which python 或 which node
路径与mcp.json中一
致
mcp.json中的路径是否为绝对
路径
检查args 字段
不包含~ 或相对路径
mcp.json格式是否有效
使用JSON验证工具检查
无语法错误
环境变量是否正确设置
检查env 字段中的变量值
Token有效,URL可达
网络是否可达(远程SSE)
curl -I
返回200
防火墙是否阻止连接
检查防火墙规则
端口和域名放行
Token是否过期
检查Token有效期
Token在有效期内
WorkBuddy版本是否≥v4.21
检查版本号
版本号≥v4.21
FastMCP包是否已安装
python -c "from fastmcp import
FastMCP"
输出"FastMCP安装成
功"

B. 连接正常但AI不调用排查清单

序号
检查项
检查方法
通过标准
工具函数是否有docstring
检查源代码
每个工具函数有完整的docstring
参数是否有类型注解
检查源代码
每个参数有类型注解(str、int、list等)
连接器开关是否打开
检查连接器管理页面
开关处于启用状态
指令是否明确指定了连接器
在对话中明确指定
如"从企业知识库中搜索..."
描述是否足够清晰
检查docstring
AI能根据描述理解工具用途

C. 连接器正常但结果异常排查清单

序号
检查项
检查方法
通过标准
权限范围是否足够
检查目标文件/数据的访问权限
在你的权限范围内
查询条件是否过于宽泛
加上时间范围和关键词限定
结果数量合理
外部服务是否正常
检查第三方服务状态页面
服务运行正常
数据格式是否正确
检查MCP服务器返回的数据格式
格式符合预期
账号是否一致
确认授权账号与数据所在账号一致
扫码账号与数据账号一致

三个反思问题

1. 当MCP协议成为AI连接外部世界的"USB-C"标准后,你的企业是否已经准备好将核心

业务系统通过MCP暴露给AI?如果还没有,最大的障碍是什么——是技术能力、安全合

规、还是组织惯性?

这个问题值得深思。MCP协议的无状态化(第五版)和企业级认证(OAuth 2.1 + OIDC)已经从协议层面解决了大部分技术障碍。但企业的真正挑战往往不在技术层面——你是否有足够的安全审计能力来评估MCP服务器的风险?你的合规团队是否理解MCP的权限边界?你的组织是否愿意让AI"触达"核心业务数据?这些问题比写一个MCP服务器难得多,但也重要得多。

2. 在WorkBuddy的"连接器+技能"混合架构中,你是否正在用"锤子拧螺丝"——用连

接器处理本该用技能解决的简单任务,或者用技能勉强处理本该用连接器的实时数据需

求?如何建立一套系统化的选择标准?

很多用户在WorkBuddy中只会使用一种工具——要么只用技能,要么只用连接器。这就像只会用锤子的木匠,遇到螺丝就用锤子砸。真正的效率来自于根据任务特点选择合适的工具。本文提供的"MCP连接器选择决策表"是一个起点,但你需要根据自己团队的实际情况,建立一套更精细的选择标准。

3. MCP协议从Anthropic的独有项目走向Linux基金会下的行业标准,这对作为用户的

你意味着什么?你应该如何在"拥抱开放标准"和"锁定特定平台"之间找到平衡?

MCP的开放标准化意味着你不再被绑定于Anthropic的生态——任何支持MCP的AI客户端都可以使用同一套MCP服务器。但这也意味着你需要关注协议的Breaking Changes(如第五版废弃Sampling),以及不同客户端对MCP特性的支持差异。作为WorkBuddy用户,你应该:关注WorkBuddy的MCP协议版本升级公告;确保自定义MCP服务器遵循最新规范;在技术选型时优先考虑MCP兼容性,而非特定平台的功能扩展。

附录:关键术语表

术语
英文
定义
MCP
Model Context Protocol
模型上下文协议,AI与外部工具/数据源的统一交互
标准
Host
MCP Host
AI应用(如WorkBuddy),协调和管理MCP客户端
Client
MCP Client
由Host为每个Server创建的连接实例
Server
MCP Server
暴露工具/资源/提示词的独立程序
Transport
Transport Layer
传输层,定义通信机制(stdio或Streamable
HTTP)
Discovery
Capability Discovery
能力发现,客户端和服务器交换协议版本和能力
Tool
MCP Tool
服务器暴露的可执行函数
Resource
MCP Resource
服务器暴露的上下文数据源
Prompt
MCP Prompt
服务器暴露的可复用交互模板
SEP
Specification Enhancement
Proposal
规范增强提案,MCP协议变更的社区流程
AAIF
Agentic AI Foundation
Linux基金会下的MCP治理组织
Function Calling
Function Calling / Tool Use
LLM的API级功能,模型返回结构化JSON指定函数
名与参数
Streamable
HTTP
Streamable HTTP Transport
MCP的远程传输机制,支持HTTP POST和可选SSE
流式
Stdio
Standard I/O Transport
MCP的本地传输机制,通过标准输入/输出流通信
OAuth 2.1
OAuth 2.1
MCP的标准化认证方案,支持PKCE流
MCP Registry
MCP Registry
MCP服务器的公共注册表,用于发现和索引
MCP Apps
MCP Apps
MCP的官方扩展,支持服务器端渲染的交互式UI
Tasks
MCP Tasks
MCP的官方扩展,支持长期运行的异步任务
Connector
WorkBuddy Connector
WorkBuddy中的连接器,基于MCP协议与外部服务
通信
Skill
WorkBuddy Skill
WorkBuddy中的技能,基于Function Calling的内
置脚本

参考来源

Model Context Protocol官方文档《Architecture overview》(2026-07-28版本)— vs Function Calling: What Is the Difference?》—mcp-vs-function-callingPortkey Blog《MCP vs Function Calling – How They Actually Work Together》(2026-03-20)—腾讯云文档《WorkBuddy Enterprise 连接器》—1831/134525腾讯云开发者社区《WorkBuddy 连接器实战:AI 终于能直接读你的腾讯文档和邮件了》(2026-05-22)—腾讯云开发者社区《从原理到落地,一文搞懂这个让 AI 模型"活起来"的革命性协议!》— Blog《Everything your team needs to know about MCP in 2026》(2026-03-26)—Safeguard.sh《Model Context Protocol in 2026: News, Adoption, and Security Landscape》(2026-07-09)—landscape钛媒体《Anthropic的HTTP时刻:MCP第五版全面无状态化》(2026-07-28)— )— Connector(CC Connect)完整实践指南》— draft)—specification/draft/architecture本文最后更新时间:2026年8月。MCP协议仍在快速演进中,建议定期关注MCP官方文档和WorkBuddy更新公告以获取最新信息。

← 上一章:WorkBuddy产品架构目录下一章:提示词工程 →