1. 先搞清楚一件事MCP 不是来取代 API 的最近圈子里聊 MCP 聊得火热尤其是在 DeepSeek、智谱这些大模型 API 频繁更新之后不少开发者产生了同一个困惑MCP 都出来了是不是以后不用再学 API 了上手 BlueMCP、Figma MCP 之后是不是写代码的方式要彻底换一遍我直接说结论MCP 和 API 不是一个赛道上的东西谈不上谁替代谁。API 的本质是接口契约它定义的是你能调用我什么能力、需要传什么参数、返回什么格式。比如 DeepSeek 的 API你往chat/completions端点 POST 一段消息它返回一段补全结果。这是点对点的通信协议。MCPModel Context Protocol的本质是上下文接入协议它解决的是 AI 模型怎么动态发现并调用外部工具的问题。你可以把 MCP 理解成一层适配层它规定了工具怎么描述自己、参数怎么传递、结果怎么返回但真正干活的还是背后那个 API。举个例子你在 Trae 里接入 Figma MCPMCP Server 拿到你的操作指令后最终去请求的还是 Figma 的 REST API。MCP 做的是把AI 自然语言指令翻译成Figma API 能执行的调用再把结果拽回来。没有 Figma APIMCP 就是空壳没有 MCPAI 就没法自动决定该调哪个接口、按什么顺序调。所以对开发者来说真正的问题不是API 还是 MCP而是什么场景用 API什么场景套 MCP以及两者怎么配合。2. API 选型的四个硬指标模型能力、上下文长度、配额与限流、中立性先聊 API。这块水最深因为 API 不是你写代码好不好决定的而是上游服务商能给你什么、限你多狠决定的。2.1 模型能力与API 模型名陷阱我见过不少人踩同一个坑照抄别人博客里的代码结果报错api error: 400 the supported api model names are deepseek-flash, deepseek-v4。原因很简单——服务商升级模型后旧模型名下架了。选 API 第一个要看的是当前可用的模型名而不是听说这个模型很强。强不强是用户体验层面的你作为开发者要确认的是三件事模型名是否在当前 API 文档的可用列表里该模型是否支持你需要的功能比如工具调用、JSON 输出、流式响应模型上下文窗口到底多大2.2 上下文长度不是越大越好是够用且不爆热搜里那条api error: 400 this models maximum context length is 1048576 tokens特别典型。1M token 的上下文看着很爽但很多开发者忽略了一个残酷事实输入 token 是按量计费的。假设你每次请求塞 500K token一秒钟发两个请求你去算算账单基本心脏骤停。所以我建议上下文选型分档对话/客服类32K 足够控制在 8K-16K 实际使用代码补全/单文件分析128K 够用塞整个项目不现实长文档理解/Agent 场景需要 256K 以上但必须配合缓存策略而不是每次都全量传另外注意上下文长度不等于你写多少字都能记住。实际上模型对长上下文中段的注意力会衰减关键信息尽量放在开头和结尾这是 Prompt 工程的常识API 选型时也要考虑进去。2.3 配额与限流最容易翻车的隐藏坑api error: request rejected (429) you have exceeded the 5-hour usage quota这类报错本质上不是你的代码问题而是你选 API 时没看清楚配额策略。选 API 必查三个数字维度要问清楚的问题影响RPM每分钟请求数每分钟最多发多少个请求并发上不去就排队TPM每分钟 token 数每分钟最多消耗多少 token长文档任务容易爆周期配额是 5 小时滚动窗口还是自然日长时间任务要规划窗口我的建议是正式项目选 API 之前先写个压测脚本跑 30 分钟把 RPM 和 TPM 同时推到接近上限看返回什么错误、错误重试后能不能恢复。很多 API 在接近配额时表现很怪——不报 429而是突然变慢甚至超时这类问题不压测根本发现不了。2.4 平台中立性你调的 API 会不会绑死你的架构还有一个容易被忽略的维度这家 API 是否只提供自家模型还是兼容 OpenAI 格式。我个人的原则是能用 OpenAI 兼容格式的 API优先选。原因不是 OpenAI 多好而是这套格式已经成为行业事实标准。今天你用 A 平台的 API明天想切换到 B 平台只要两边都兼容 OpenAI 格式你只需要换 base_url 和 key代码改动量极小。反过来如果某个 API 只有私有格式你一旦深入使用后面所有工具链都得围着它转换平台等于重写。这一点在做技术选型时非常关键。3. MCP 的选型思路先想清楚你要让 AI 替你干什么MCP 的热度不是虚的但很多开发者对 MCP 的理解停留在AI 能读 Figma 了AI 能操作浏览器了这种表面。真正落地时需要先回答一个问题你希望 AI 以什么方式介入你的工作流3.1 MCP 的两种用法辅助生成 vs 自动化操作我观察下来MCP 在开发者场景里实际分两类。第一类是辅助生成型。典型代表是蓝湖 MCP、Figma MCP。开发者用 Trae、Codex 这类 AI 编程工具时AI 需要看到设计稿才能生成还原度高的前端代码。Figma MCP 做的事就是把设计稿的结构、颜色、文字、间距这些信息抽取出来变成 AI 能读的 JSON 文本。这种场景下MCP 是给 AI 喂信息的管道。第二类是自动化操作型。典型代表是 Playwright MCP、Burp MCP。AI 不只读静态信息还要真正去操作浏览器、发起请求、分析响应。比如 Playwright MCP 可以让 AI 自己打开网页、点击按钮、填写表单、截图然后把结果反馈回来。这类 MCP 对权限控制要求更高因为你等于把控制权交给了模型。选型前先分清楚你要哪类。辅助生成型的 MCP 接入简单、风险低自动化操作型的 MCP 能力上限高但你必须做好流程管控否则 AI 一顿操作猛如虎最后把生产环境改了你都不知道。3.2 MCP Server 的三种实现路径不是说只有官方提供 MCP Server 你才能用。实际上开发者接触到的 MCP 有三种来源官方 MCP Server比如 Figma 官方出的稳定性和权限模型都比较完善优先用社区自建 MCP Server比如有人写了 Blender MCP用法和 App 开发里调用 REST API 高度一致性需要审查它的工具定义是否合理自己写 MCP Server本质上是一个本地 HTTP 服务用 JSON-RPC 协议暴露工具列表和调用入口。你的快递查询 API、内部系统 API、数据库查询接口都能包一层 MCP 让 AI 调用很多开发者忽略的是第三种。其实把企业内部 API 封装成 MCP Server是当前成本最低、收益最高的 AI 应用改造路径。你不需要重写业务逻辑只需要写一层协议转换。3.3 MCP 的上下文消耗比想象中大用 MCP 有个容易被忽略的问题工具描述会占用上下文窗口。每个工具的定义包括名称、描述、参数 schema、示例这些都要塞进 context 里。你暴露 20 个工具每个工具描述 500 token光工具说明就吃掉 10K token。如果你用的模型上下文只有 32K留给实际对话和结果处理的就非常紧张。所以自建 MCP Server 时有一个原则工具数量宁少勿多工具描述宁短勿长。只暴露当前场景必须的工具描述写清楚什么时候用和关键参数含义就够了别把文档复制进来。3.4 MCP 与工具链的适配不是所有 MCP 都能跑在任意客户端注意MCP 是协议客户端是否支持同样关键。比如你在 Codex 里配 Figma MCP和你在 Trae 里配适配路径完全不同。Figma MCP 能不能直接切图取决于客户端是否支持那种工具调用方式而不是 MCP Server 本身的问题。我在实操中的做法是先确认 AI 编程工具是否原生支持 MCP 配置现在 Trae、Codex、Cursor 基本都支持再确认 MCP Server 的传输方式stdio 本地进程 vs SSE 远程服务最后确认客户端是否支持多 MCP 同时启用多个 MCP 时工具命名空间会不会冲突这三点不确认后面很容易出现MCP 配置了但 AI 根本不用的尴尬局面。4. 实操避坑MCP 接入失败、权限校验、以及和浏览器开发者模式的区分进入实践环节。我把最近群里问得最多的几类问题集中拆一下按排查链路走一遍而不是直接给答案。4.1 MCP Server 连不上先分清楚是启动问题还是协议问题很多人接入 MCP 时报错第一反应是去检查网络。但 MCP 最常见的失败原因恰恰是本地启动失败。MCP Server 如果是 stdio 模式客户端会直接拉起一个本地进程然后通过标准输入输出通信。这时候大多数情况是Node 版本不对MCP SDK 要求 Node 18Python 环境缺依赖pip install不完整环境变量没设置MCP Server 内部调用 API 时拿不到 key排查的顺序我建议按这个来先在终端手动运行mcp-server启动命令看能不能正常输出手动发一个initialize请求看是否返回协议握手成功再让客户端去连接这时候如果还报错就说明是客户端配置问题很多人跳过前两步直接去调客户端配置绕了一大圈结果发现是本地服务根本没起来。4.2 API 调用失败报错信息里藏着 70% 的答案开发者日常遇到最多的 API 问题其实只要养成分层排查的习惯80% 能快速定位报错类型根因方向排查动作400 invalid model name模型名过时或不存在查 API 文档当前模型列表别信旧博客400 context length exceeded输入 token 超窗口精简上下文或换成更大窗口模型401 unauthorizedkey 失效或无权限检查 key 状态、是否有环境变量覆盖429 rate limit触发配额限制查看配额周期做退避重试500 internal error服务端临时故障重试或检查参数是否导致服务端异常有一个容易被忽略的点401 和 403 的根因经常是环境变量冲突。比如你.env里配了一个API_KEY但系统全局变量里又有一个同名变量部分语言的 SDK 读取优先级是环境变量优先于.env结果你以为加载的是新 key实际用的是旧 key。排查的时候在代码里打印出来看一眼能省半天时间。4.3 浏览器开发者工具里 Network 请求不显示和 API 调试的关系热搜里有一条chrome 浏览器开发者工具无法正常显示 network 请求很多人以为这是 API 调用失败导致的。其实这个是浏览器调试层面的经典问题。最常见的两个原因开启了缓存后续请求走了from disk cacheNetwork 面板不显示完整链路页面跳转后之前的请求被清掉了但你忘了勾选preserve log调试 API 时我建议的配置是打开 Network 面板后立即勾选Preserve log然后Disable cache再刷新页面。这样不管页面怎么跳转你都能看到完整的请求链路包括请求头、响应体、重定向过程。这个技巧对于调试前端调后端 API 报 429的场景特别有用——你能直接看到是不是有某个静态资源请求也带着 API key蹭掉了配额。4.4 微信开发者工具/小程序场景的专属坑开发版小程序已过期请在开发者工具重新扫码这条属于遇到一次就懂的问题。开发版小程序的登录态有有效期过期后必须通过开发者工具重新扫码刷新。这不是代码 bug而是平台策略。解决办法是在开发者工具里重新点编译或者重新预览系统会提示重新扫码。很多时候顺手切换一下右上角的普通编译/自定义编译模式也能触发刷新。另外检测到开发者工具已打开请关闭后刷新页面继续访问这类提示一般是你在浏览器里用开发者工具调试时本地调试服务和开发者工具冲突导致的。处理办法很简单关闭多余的开发者工具窗口或者在配置里换个调试端口。这些坑看起来和 API/MCP 选型无关但实际项目里总会碰到。我的经验是API 和 MCP 的选型不只是选技术更是选一套工作流周边工具链的顺手程度直接影响开发效率。5. 开发者如何根据实际场景组合 API 与 MCP聊到这里核心问题浮出水面具体到实际开发中API 和 MCP 到底怎么组合用我的建议是按场景分四类。5.1 日常后端开发API 为主MCP 辅助生成测试这类场景你的核心工作本来就是写接口、调接口。直接用 API 是最可控的——因为你要调试的是接口本身的行为而不是让 AI 去猜接口什么行为。但可以引入 MCP 做辅助比如把你自己服务的 OpenAPI Schema 封装成一个 MCP Server让 AI 编程助手读取这个 Schema自动生成测试用例。这种用法下API 是被测试对象MCP 是让 AI 理解被测试对象的方式。我给一个具体落地步骤你已有的 REST API 保持不动写一个简单的 OpenAPI 导出脚本把你项目里的路由自动生成openapi.json用社区现成的openapi-to-mcp之类的工具把这个 JSON 包成 MCP Server在 Trae/Cursor 里配置这个 MCP然后你只需要说给 /order/create 接口写一个包含边界值的测试用例AI 就能根据工具定义自动生成这里面 API 的价值在于稳定、可控、可调试MCP 的价值在于把 API 的能力喂给 AI减少你手写上下文的工作量。5.2 AI Agent 类项目MCP 是通路API 是能力如果你在做一个稍复杂一点的 Agent——比如根据用户描述自动创建 Jira 工单 生成代码 提交 PR那这个 Agent 背后要调用的系统可能有好几个。这时候如果你让 Agent 直接记住每个系统的 API 文档上下文会爆炸而且每次系统接口变更你都要去改 Prompt。正确的做法是给每个系统做一个 MCP Server暴露少量核心工具。Agent 只需要知道有个工具能创建 Jira 工单有个工具能提交 PR具体怎么调 API 由 MCP Server 处理。这就像你雇了一个项目经理MCP去协调各个供应商API。你不用直接跟每个供应商打交道只需要告诉项目经理你要什么。这种架构下API 和 MCP 的分工是API 层负责具体业务逻辑比如创建工单获取用户信息提交代码MCP 层负责语义映射——把 Agent 的模糊意图翻译成精确的 API 调用序列Agent 层只负责拆解任务、组织对话、判断下一步调哪个工具这样的好处是任何一个 API 升级了你只需要在 MCP Server 内部适配Agent 层完全不受影响。5.3 设计稿转代码MCP 是唯一高效路径Figma MCP 怎么运用在 Trae这类问题本质是怎么让 AI 看到设计稿。以前的做法是你把 Figma 设计稿的图片截图拖进对话框让 AI 看图写代码。但截图有分辨率限制AI 对细微的颜色值和间距拿不准。而且设计稿更新后你还要重新截图。用 Figma MCP 之后AI 可以直接通过工具读取设计稿的结构化数据——包括颜色、字体、图层层级、布局约束。这意味着你可以让 AI按照 /design/login-page 这个 Frame 的样式写一个 React 组件设计稿更新后你不重新截图直接让 AI对比 /design/login-page 和 /design/order-page 的样式差异这里有一个细节不是所有客户端都支持远程 MCP。Figma 官方 MCP Server 走的是远程连接你的 AI 编程工具需要支持 SSE 传输类型才连得上。Trae 目前是支持的但配置时注意填对 URL 和 token 的获取方式。Figma 个人 token 在 Account Settings 里生成别用错了。5.4 蓝湖 MCP 的接入思路关注工具描述而非连接成功很多人在蓝湖 MCP 这类工具上花了很多时间最后发现 AI 调用效果一般。我复盘下来问题通常出在没有理解工具描述对决策的影响。MCP 工具列表本质上就是给 AI 看的菜单。如果菜单写得不清不楚AI 就不知道怎么点菜。比如你暴露了一个获取切图 URL的工具描述写的是获取指定模块的切图资源AI 大概率不会主动用它。但如果你写的是当设计稿中存在切图需求时调用该工具获取当前选中 Frame 的切图 URL参数 frame_id 从设计稿元数据中获取AI 就知道该在什么时候用了。所以自建 MCP 或者评估一个现成 MCP 时我建议你重点看它的tool description 质量而不是看它支持多少功能。工具多而描述模糊不如工具少而描述精准。6. 一个实战案例把内部知识库 API 封装成 MCP Server 的全过程最后用一个完整案例来串联全文——把一个简单的知识库搜索 API 封装成 MCP Server。这个例子很典型因为几乎所有团队都有内部文档/知识库AI 如果能直接查询效率提升会非常明显。6.1 前置准备假设你有一个知识库系统的 API接口如下GET /api/search?q关键词limit10返回 JSON 结构大致是{ code: 0, data: { total: 3, items: [ { id: 123, title: 部署手册-生产环境, snippet: 生产环境使用 Docker 部署nginx 映射 8080 端口..., score: 0.96 } ] } }你现在要做的是让 AI 能通过自然语言搜到这个知识库的内容。6.2 用 Python 快速实现MCP 官方提供 Python SDK库名是mcp。写一个最小 Server 只需要三步。先安装依赖pip install mcp httpx然后写一个搜索工具import json from mcp.server import Server, NotificationOptions from mcp.server.models import InitializationOptions import mcp.server.stdio from typing import Any import httpx # 知识库 API 的基础配置 KB_BASE_URL http://your-kb-service.internal/api KB_API_KEY your-api-key app Server(kb-search-mcp) app.list_tools() async def list_tools() - list[dict[str, Any]]: 向客户端暴露工具列表 return [ { name: search_knowledge_base, description: 当用户问题涉及内部文档、部署手册、历史决策记录时调用该工具搜索知识库, inputSchema: { type: object, properties: { query: { type: string, description: 搜索关键词从用户问题中提取核心关键词不用包含多余修饰 }, top_k: { type: integer, description: 返回结果数量默认 5, default: 5 } }, required: [query] } } ] app.call_tool() async def call_tool(name: str, arguments: dict[str, Any]) - list[dict[str, Any]]: 执行工具调用 if name ! search_knowledge_base: raise ValueError(fUnknown tool: {name}) query arguments[query] top_k arguments.get(top_k, 5) # 调用内部知识库 API async with httpx.AsyncClient() as client: resp await client.get( f{KB_BASE_URL}/search, params{q: query, limit: top_k}, headers{Authorization: fBearer {KB_API_KEY}} ) resp.raise_for_status() data resp.json() # 把结果拼成纯文本方便 AI 直接读取 results [] for item in data[data][items]: results.append(f标题{item[title]}\n摘要{item[snippet]}) return [ { type: text, text: \n\n.join(results) if results else 未找到相关文档 } ] async def main(): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await app.run(read_stream, write_stream, InitializationOptions( server_namekb-search-mcp, server_version0.1.0 )) if __name__ __main__: import asyncio asyncio.run(main())6.3 为什么这样写几个设计决策值得说明一下工具描述写清楚触发时机。当用户问题涉及内部文档、部署手册、历史决策记录时这句话很重要它告诉 AI 什么时候该用这个工具。这个边界描述越清晰AI 的误调用就越少。返回纯文本而非原始 JSON。MCP Server 返回给客户端的格式是 text 或 resource 形式。直接把 JSON 原样返回也不是不行但 AI 在上下文里解析 JSON 的结构化信息时会消耗更多 token。如果只是提供摘要信息拼成纯文本更高效。把 API key 放在服务端环境变量。不要让 AI 直接接触内部 API 的鉴权信息——MCP Server 是隔离层它负责安全地调用内部 APIAI 只看到加工后的结果。6.4 用 MCP 客户端验证这个 Server 写好之后你可以用专门的调试工具测试也可以直接在支持 MCP 的客户端里配置。配置方式通常是在客户端里选择添加 MCP Server类型选 stdio命令填python path/to/kb_search_mcp.py然后在对话框里输入一句查一下生产环境怎么部署如果配置正确AI 应该会调用search_knowledge_base工具返回知识库里相关的部署文档。实际测试中你会发现AI 不会什么问题都去搜知识库。它会判断当前问题是否真的需要查文档如果你问的是11 等于几它不会傻乎乎去调用工具。这就是 MCP 相比把所有文档塞进 Prompt的最大区别按需检索节省大量上下文。6.5 这个案例背后的选型心法回看这个案例你会发现它完整涵盖了我前面说的几个原则API 负责真正的业务能力——知识库搜索是人家系统本来就有的事MCP 只做协议适配和语义映射——把搜索知识库这个工具合适地暴露给 AI工具描述决定 AI 是否调用——写清楚触发时机和参数含义不是随便糊弄安全边界由 MCP 层守住——内部 API 的 key 和网络拓扑都不会泄露给模型以后如果你要接新的内部系统比如去查工单系统、查数据库、查监控指标套一个同样的模式往里填就行。成本不高收益却很直接。7. MCP 生态的现状和生产环境里的一些实话写到这里我必须说点实在的。MCP 这个生态还很年轻不是所有东西都那么美好。7.1 你能拿到的 MCP Server 质量参差不齐社区里有很多第三方封装的 MCP Server比如 Blender MCP、devspace MCP、Figma MCP、Playwright MCP 这些。有的维护得不错有的就是作者周末写来玩的工具描述不全、错误处理稀烂、甚至有安全漏洞。我的评估标准很简单看 GitHub 仓库的 issue 响应速度看是不是有版本发布记录看工具描述是否足够详细看是否支持自定义配置比如自定义 API 地址、超时时间前两条过滤掉大部分玩具项目后两条决定你能不能塞进正式工作流。7.2 MCP 的标准化程度还不够高MCP 协议本身在快速演进但生态里很多细节并没有完全统一。比如有的 Server 用 stdio有的用 SSE有的用 Streamable HTTP认证方式五花八门有的靠环境变量有的靠 OAuth有的干脆不做认证工具描述的语言风格差异也很大用中文还是英文会影响 AI 的理解质量所以接入任何 MCP Server 之前花 20 分钟读一下它的 README 是值得的。别只会在客户端里点添加然后抱怨连不上。7.3 如果你要被 MCP 或者 API 面试/写进简历老实讲一句最近确实很多人来问我要不要把 MCP 写进简历。我的态度是可以写但别只写MCP三个字。你要写清楚的是什么场景下用了什么 MCP Server、解决了什么具体问题、把 API 调用效率提升了多少、上下文消耗降低了多少。同样的道理也适用于 API。写熟练使用 DeepSeek API是没有意义的写针对 1M token 上下文窗口设计了一套分层缓存策略将 API 成本降低 60%才有含金量。技术选型这件事真正值钱的是你踩过坑之后形成的判断力——知道什么时候用 API、什么时候套 MCP、怎么让两者配合得高效以及出了问题怎么快速定位。我自己的习惯是新项目启动时先画一张简图把用户请求→AI 层→MCP 层→API 层→内部系统的链路走一遍标清楚每一层的职责边界。画完之后选型自然就清楚了。这个习惯你也可以试试。