DeepSeek V4 接入 MCP 实战：给 Agent 装上「手和脚」

生命不息，折腾不止。上一篇我们把代码从旧模型名迁到了 V4，今天再往前一步：把 MCP 接上，让 Agent 真正长出手和脚，能调工具、能干活。

一、MCP 是啥？为什么 2026 年你必须会

先花 30 秒把概念捋清楚，不然下面全是黑话。

MCP（Model Context Protocol，模型上下文协议） 是 Anthropic 在 2024 年 11 月开源的一个开放标准，江湖人称 「AI 应用的 USB-C 接口」。意思很直白：以前每个 AI 工具接一个新数据源，都要单独写一套集成代码，维护成本爆炸；MCP 把「工具提供方」和「AI 应用方」彻底解耦——一个 MCP Server 写一次，Claude、GPT、Gemini、DeepSeek 通吃。

这两年它已经从「Anthropic 家的小协议」长成事实标准了：OpenAI、Google、Microsoft 全都原生支持，Python + TypeScript 两个 SDK 月下载量逼近一个亿，官方 Registry 里登记的 Server 接近一万个。所以学 MCP 不是追新，是补 2026 年的基本功。

它的架构就三层，记住这张图：

Host（宿主）：你天天用的 AI 应用，比如 Claude Code、Cursor、Claude Desktop
Client（客户端）：Host 内部为每个 Server 开的一条连接，你不需要管它
Server（服务端）：提供外部能力的进程，比如 GitHub、数据库、文件系统、天气 API

Server 对外只暴露三种东西：工具（Tools）——模型能调用的函数；资源（Resources）——模型能读的数据；提示词（Prompts）——预写的模板。日常折腾 90% 都在跟 Tools 打交道，今天的实战也围绕它展开。

传输方式有两种：stdio（本地进程，Claude Code / Cursor 默认）和 Streamable HTTP（远程服务，2025 年 11 月规范引入，老掉牙的 SSE 已被官方淘汰）。

二、DeepSeek V4 接 MCP 的底牌：双兼容 + 一个致命坑

DeepSeek V4（2026 年 4 月 24 日发布，MIT 协议）天生就是干这活的料，原因有仨：

1. 接口双兼容，客户端即插即用。 V4 同时提供 OpenAI 兼容和 Anthropic 兼容两套 API，base URL 都是 https://api.deepseek.com，官方文档的示例代码直接填这个地址即可。任何 MCP 客户端只要把模型名填成 deepseek-v4-pro 或 deepseek-v4-flash，直接就能用，不需要任何代理和中间层。

2. 1M 上下文，长任务不爆。 V4 两个模型都支持 100 万 token 上下文，配合它家新的混合注意力架构（KV 缓存省约 90%），以前跑长上下文 Agent 动不动 OOM 的场景，现在便宜又流畅。

3. 便宜。 MCP 干活是典型的「多轮工具调用」：模型列工具 → 调工具 → 读结果 → 再调……一个用户问题背后可能是 3-5 次 API 调用。这个场景下 V4 的价格优势被放大得很明显，flash 干杂活、pro 出结论，成本比国外旗舰低一个量级。

但有个致命坑必须先说：别把 deepseek-r1 指给 MCP 客户端！ R1 这个老模型从设计上就不支持 function calling（工具调用），V4 发布也没改变这一点。你把 MCP 客户端指向 r1，它不会报错，而是一本正经地编造工具输出——看起来像调了工具，实际全是幻觉，这在 Agent 场景里是灾难级的。记住：凡是要接 MCP、要调工具的活，一律用 deepseek-v4-pro 或 deepseek-v4-flash。

三、实战一：3 分钟把现成的 DeepSeek MCP Server 接进 Claude Code

先说最省事的路径：社区有人把 DeepSeek 的 API 包装成了标准 MCP Server，装好直接当工具用。以 @arikusi/deepseek-mcp-server 为例（npm 包名 deepseek-mcp-server，MCP Registry 有登记，也有其他同类项目，比如 DMontgomery40/deepseek-mcp-server，原理一样）：

第 1 步：拿到你的 DeepSeek API Key

去 DeepSeek 开放平台（platform.deepseek.com）创建一个 Key，形如 sk-xxx。充个 20 块够折腾很久。

第 2 步：一条命令注册进 Claude Code

1
2
3

claude mcp add -s user deepseek \
  npx @arikusi/deepseek-mcp-server \
  -e DEEPSEEK_API_KEY=sk-你的key

解释一下：-s user 表示对当前用户全局生效（想只对某个项目生效就把 -s user 换成 -s project）；后面 npx @arikusi/deepseek-mcp-server 是启动命令，npm 会自动拉包，无需手动安装；-e 把 API Key 传进这个子进程的环境变量。

第 3 步：重启 Claude Code，验证注册成功

完全退出 Claude Code 再重新进入（MCP 配置只在启动时加载），然后敲：

/mcp

能看到 deepseek 服务器出现在列表里就成功了。它的工具大概长这样：deepseek_chat（对话）、deepseek_fim（代码补全）、deepseek_sessions（多轮会话），还带成本统计。

第 4 步：让它干活

直接下指令试试，比如：

1	用 deepseek 工具帮我写一个 Python 快排，要求带注释

Claude Code 会把 deepseek_chat 工具连同你的问题一起发给模型（此时驱动 Claude Code 主循环的可以是任何模型），DeepSeek 返回结果后作为工具结果回传，你看到的是一套完整的「Agent 把活外包给 DeepSeek」的流程。默认模型是 deepseek-v4-flash，追求质量可以在调用参数里指定 deepseek-v4-pro。

想删掉这个工具：claude mcp remove deepseek。想查看配置详情：claude mcp get deepseek。

四、实战二：20 行代码写一个自己的 MCP Server

现成的 Server 是别人给你做好的轮子，但真正的乐趣是给自己的数据写工具。用 Python 的 FastMCP 库，20 行代码搞定。以下以官方快速入门为基准，用最新版（FastMCP 3.x）写法：

第 1 步：装环境（用 uv，一行命令装好）

curl -LsSf https://astral.sh/uv/install.sh | sh
uv init my-mcp && cd my-mcp
uv venv && source .venv/bin/activate
uv add "mcp[cli]" httpx

第 2 步：写你的第一个工具

新建 server.py，复制粘贴：

from fastmcp import FastMCP

mcp = FastMCP("my-tools")

@mcp.tool
def add(a: int, b: int) -> int:
    """两个整数相加，先拿它练手"""
    return a + b

@mcp.tool
def get_weather(city: str) -> str:
    """模拟查天气，真实项目里这里换成 requests 调天气 API 即可"""
    return f"{city} 今天晴，26℃"

if __name__ == "__main__":
    mcp.run()  # 默认 stdio 传输

看到了吗？一个 @mcp.tool 装饰器，函数签名 + 中文注释，工具定义、参数校验、文档生成全自动。这就是 FastMCP 的全部魔法。

第 3 步：先本地跑通（可选）

1	fastmcp run server.py

会以 stdio 模式启动。想远程访问就加传输参数：

1	fastmcp run server.py --transport http --port 8000

第 4 步：接进 Claude Code

1	claude mcp add -s user my-tools python /绝对路径/server.py

重启 Claude Code 后 /mcp 里就能看到 my-tools。现在你可以让它「算一下 127 和 358 的和」，看它怎么一步步调用 add 工具；或者加个真天气 API，让 DeepSeek V4 帮你查全球任意城市的天气——模型负责理解，工具负责执行，这就是 Agent 的最小形态。

五、避坑清单（都是真金白银换来的）

模型名必须写对。 MCP 客户端里只填 deepseek-v4-pro / deepseek-v4-flash。填 deepseek-r1 会幻觉工具输出；填 deepseek-chat / deepseek-reasoner 这些 2026 年 7 月已退役的旧名会直接报错。
API Key 一定要传进 Server 进程。 用 claude mcp add 时 -e DEEPSEEK_API_KEY=... 不能漏；手动启动的话先 export DEEPSEEK_API_KEY=sk-xxx。忘了传的表现是 Server 起来但一问就 401。
base URL 要认准。 官方是 https://api.deepseek.com，有些教程让你填别的兼容端点，请确认来源可信。走第三方兼容端点时，记得模型名也要按对方文档改（比如换成你自己的中转站模型名）。
改完配置必须重启客户端。 Claude Code 只在启动时加载 MCP，热改配置不生效，claude mcp add 完没重启然后到处找 bug 的，都是这一步栽的。
别用 SSE 老传输。 2025 年 11 月之后的规范已经切到 Streamable HTTP，新写远程 Server 直接上 HTTP；看到「SSE」字样的老教程留个心眼，写法可能过时了（以官方文档 modelcontextprotocol.io 为准）。
本地 Server 别开公网。 自己写的 stdio Server 只服务本机；要远程用就加 OAuth 认证，裸奔在公网等于把工具权限白送。

六、下一站：让 Agent 打组合拳

今天这两套实战下来，你已经能给 DeepSeek V4 接上「手和脚」了：现成的 Server 拿来即用，自定义工具 20 行就能上。接下来就是组合拳阶段——把 DeepSeek V4 接进 Claude Code 当主力模型，再配上 MCP 工具，一套完整的低成本 Agent 工作台就搭起来了。

顺带说一句，如果你想让 Claude / GPT / Gemini 这些国外模型也走同样的 MCP 玩法，又不想折腾海外信用卡和网络，可以看看 ai.aklibk.com 中转站：一个 Key 通吃 Claude / GPT / Gemini / DeepSeek，人民币按量付费，国内直连免绑卡，DeepSeek 系模型价格还更便宜——同一套 MCP 配置，改个 base URL 和模型名就能切换底层模型，这正是「写一次、处处可用」的价值所在。