把MCP搬到手机端：移动AI工具链的架构设计与实践

最近在折腾移动端 AI 工具链，发现 MCP 这个关键词已经躲不掉了。所谓 mobile-mcp，就是我正在做的一个项目：把 Model Context Protocol 放到手机上跑，让大模型能真正调用到手机上的本地能力——通知、定位、摄像头、传感器、剪贴板，而不是只在一个云端沙箱里打转。这个项目解决的核心问题很直接：AI 助手和真实移动设备之间有道墙，MCP 就是拆墙的工具。这篇博文会把我的整体设计、核心模块、实操步骤和踩坑记录完整写出来，适合正在做移动端 AI 应用、或者想把自己的智能硬件/手机助手接入 MCP 生态的开发者参考。

1. 从 MCP 到 mobile-mcp：为什么要在手机上承载协议层

1.1 MCP 是什么：AI 世界的“通用插口”

MCP（Model Context Protocol）最早是 Anthropic 推出来的一套开放协议，解决的是大模型和外部工具之间的互联问题。它的设计思路很像 USB-C：不管你是摄像头、U盘还是显示器，都通过同一个物理接口和电脑通信，协议层标准化，设备之间不再需要一堆转接头。MCP 把“工具调用、资源读取、提示词复用”这三件事抽象成了标准接口，大模型通过 MCP 客户端去发现并调用远端或本地的能力。

过去我们接一个第三方 API，通常是为某一个模型单独写一套 function calling 的 JSON 定义，再写一套请求调度逻辑。模型换一个，工具可能就得推倒重来。MCP 出现之后，工具提供方只需要实现一份 MCP Server，任何支持 MCP 的客户端（Claude Desktop、各类 Agent 框架）都能直接拉起来用。这套抽象在服务端世界已经跑得很成熟了，但放到移动端，情况要复杂得多。

我一开始想得很简单：既然 MCP Server 本质上就是一个跑的进程，那手机上也跑一个不就是了？可真正动手才发现，移动环境里“跑一个进程”这个事本身就充满了限制。手机有后台冻结机制，有权限弹窗门槛，有网络切换频繁的问题，还有应用商店对敏感权限的审查。mobile-mcp 这个项目就是在回答一个问题：移动端要有怎样一套 MCP 实现，才不是“能跑但没人敢用”的玩具。

1.2 移动端接入 MCP 的核心矛盾

传统 MCP 的部署场景基本是桌面和服务器。Server 常驻，客户端连上就能用，传输层用 stdio（标准输入输出）或者局域网 HTTP 都行，网络相对稳定，权限基本不受系统限制。但在 Android / iOS 上，这些前提全部不成立。

第一个矛盾是进程生命周期。手机操作系统随时可能杀掉你的后台进程，尤其是国内 ROM 的激进省电策略，一锁屏就把 App 的联网和计算能力冻结。MCP Server 如果保活做不到，一次长对话中间断线，状态就丢了。

第二个矛盾是权限与安全体验。MCP 的一个重要能力是让模型调用工具，但手机上的工具大多涉及敏感权限：读取位置、读取联系人、发送通知、访问相册。如果模型每次调用都直接执行，用户隐私和安全完全失控。可如果每步都弹十次授权框，体验又废了。MCP 协议本身只定义了调用的通道，并没有定义移动端的授权交互规范，这块必须自己补。

第三个矛盾是网络模型。移动网络在 Wi-Fi 和蜂窝数据之间切换时 IP 会变，HTTP 长连接会断，socket 也会断。MCP 目前的 Streamable HTTP 传输要求客户端维护会话 ID，一旦断网重连，会话上下文就丢了。这些细节在桌面端没人关注，在移动端全是主流程问题。

1.3 这个项目的定位与选型

mobile-mcp 不是一个单纯的 SDK，也不是一个完整的 App，它更像一个“移动端 MCP 适配层”。具体来说，它包含三个部分：一个内嵌在 App 里的 MCP Host（负责和远端模型/Agent 通信），一组把手机本地能力包装成 MCP Tools 的 Server 实现，以及一套处理权限确认、后台保活、网络切换的运行时逻辑。

技术选型上，我最后选了 TypeScript。原因很简单：MCP 官方 SDK 目前对 TypeScript/JavaScript 的支持最成熟，@modelcontextprotocol/sdk可以直接跑在 React Native 的 Hermes 引擎上，也能通过 Node.js 跑在桌面端做联调。Flutter 和 Kotlin 的社区实现还比较初级，没必要给自己挖坑。另外，JS 生态里 JSON Schema 的处理、HTTP 客户端、WebSocket 等库都很顺手，对快速迭代原型非常友好。

实际架构上，我采用“Host 在端上、Server 可本地可远端”的混合模式。简单场景下，手机 App 里直接内嵌一个 MCP Host，模型服务跑在云端，工具服务跑在端上；复杂场景下，手机本身也可以作为 MCP Server，被同一局域网内的其他设备调用。两种模式各有用途，下面会展开讲。

2. 核心模块拆解：设备能力如何变成 MCP 工具

2.1 工具调用（Tools）设计：把系统 API 翻译成 JSON Schema

MCP 的工具调用本质上就是让模型输出一个符合预设 JSON Schema 的调用请求，客户端解析后执行，再把结果回传给模型。所以 mobile-mcp 的第一个核心模块，是把手机系统能力翻译成结构化定义。

这里有个容易被忽视的细节：MCP 工具定义里的inputSchema，不是越精确越好，而是越简单越好。大模型是通过 JSON Schema 来理解“这个工具能干什么、参数怎么填”的，如果 schema 复杂到嵌套了四五层，模型大概率会在调用时漏填参数或填错格式。以我封装的通知工具为例，最初版本用了完整的 Notification 字段定义，包括渠道、优先级、震动模式、桌面角标等等，结果模型经常把channel_id漏了，调用成功率只有六成。后来我把暴露给模型的 schema 精简成四个字段：标题、正文、可选的附加数据、是否使用震动。其余能力全部隐藏，由 App 侧根据 notification 的属性做默认处理。调用成功率一下就上去了。

另一个关键点是错误返回的设计。工具执行失败时，不能只返回一个error字符串，最好返回一个结构化的对象，例如包含code、message、可恢复提示。这样模型在下一轮就能根据错误信息自行调整参数，而不是绕圈子重试。

{ "success": false, "error": { "code": "PERMISSION_DENIED", "message": "用户未授予通知权限", "recoverable": true } }

2.2 上下文组织：Resources 和大模型怎么合作

MCP 除了 Tools，还有 Resources 和 Prompts。Resources 在我这个项目里的典型用途，是暴露手机的上下文数据源，比如当前连接的网络状态、地理位置、日历日程、剪贴板内容。这里有一个边界问题需要想清楚：资源数据是“由模型按需读取”的，不是一股脑全塞给模型的。如果你把一个包含数百条联系人数据的列表暴露为 Resource，模型读取的时候会消耗大量 token，而且大部分数据根本用不上。

我的做法是，把资源访问做成“两级结构”：第一级是资源目录，只返回类型和元数据；第二级才是具体内容。比如device://context/network这个 URI，读取时只返回网络类型、信号强度、是否代理等轻量信息；要想拿详细状态，模型会指定device://context/network/detailed。这样既能控制 token 消耗，又能保证数据真实可用。

Prompts 则适合放一些固定的任务模板。比如“生成一条短信回复”这个任务，它的 prompt 可以预置为“你是一个手机助手，请根据用户的意图生成一条不超过70字的中文短信，并直接返回 JSON”，配合工具调用，每次执行都复用这段逻辑，不用让模型自由发挥。这类模板工程化之后，整个应用的响应稳定性会提高很多。

2.3 权限确认：移动端最大的一道自研题

MCP 协议本身没有定义权限确认的交互方式。在桌面端，用户基本信任本地执行的工具；在移动端，这完全行不通。我的方案是引入一个“敏感度分级”机制。每类工具在注册时声明自己的敏感等级，低敏感（如获取当前时间）直接执行，中敏感（如读取剪贴板）在对话流里插入一条确认卡片，高敏感（如读取位置、发送短信）必须弹独立授权页，由用户手动确认后后调用。

这里踩过一个比较大的坑：如果确认弹窗在模型执行完一轮后才出现，用户点击“同意”之后，上一轮对话的上下文可能已经丢了。所以我处理的方式是，在 Host 层拦截工具调用请求，先把“用户是否已授权”作为前置条件，未授权时直接把工具调用标记为“等待确认”，并向模型返回一个中间态。下一轮用户确认后，Host 再重新发起调用。这个机制相当于在 MCP 协议之外做了一层自己的状态机，但它能解决体验的一致性。

type ToolConfidence = "auto" | "confirm" | "strict_confirm";

对于strict_confirm级别的工具，Host 在生成工具调用参数前，会先检查权限缓存；如果没有授权记录，直接向模型返回“该工具需要用户授权，请等待用户操作后重试”，然后触发本地授权 UI。这样模型不用猜，用户也不会被突然打断得莫名其妙。

2.4 会话状态与上下文生命周期

移动端还有一个桌面端不需要过度操心的问题：一个大模型会话可能持续几十分钟，中间用户可能切换 App、接电话、锁屏。会话状态如果全部放在内存里，操作系统一杀进程就全丢了。我的选择是，把会话核心状态（工具调用的请求 ID、授权状态、资源 URI 列表）持久化到本地 SQLite，同时把大体积的上下文（比如历史消息）按需重组。这样即使 App 被系统回收，重建时依然可以从断点恢复。

此外，MCP 的 Streamable HTTP 传输会给每个会话分配一个Mcp-Session-Id，这个 ID 也需要持久化。移动网络切换时，HTTP 连接断掉不可怕，只要 Session ID 还在，重新连接后仍可恢复上下文。这个 ID 其实相当于服务端会话的一把钥匙，丢了就真的从头开始了。

3. 实操：从零搭建一个 mobile-mcp 运行环境

3.1 项目骨架和最小依赖

我建议直接用 TypeScript + React Native 起步，调试时先在 Node.js 环境跑通 MCP Server，再挪到移动端。项目初始化可以用你熟悉的 CLI，核心依赖只需要一个：

npm install @modelcontextprotocol/sdk

其他例如react-native-permissions、@react-native-community/geolocation、@react-native-community/netinfo，看你要接什么本地能力来加。

一个最精简的 mobile-mcp 工程大致长这样：

mobile-mcp/ ├── src/ │ ├── server/ │ │ ├── index.ts # MCP Server 入口 │ │ ├── tools/ │ │ │ ├── notification.ts │ │ │ └── location.ts │ │ └── resources/ │ │ └── device.ts │ ├── host/ │ │ ├── mcpHost.ts # 客户端连接管理 │ │ └── permission.ts # 权限分级控制器 │ └── native/ │ └── bridge.ts # React Native 桥接层 └── package.json

我在本地先跑一个纯 Node 版本的 Server，用McpServer类注册工具，然后通过StdioServerTransport或StreamableHTTPServerTransport对外提供服务。移动端正式运行时，不会再走 stdio，而是走 HTTP，但本地调试 stdio 的速度优势很明显，能省掉大量打包和日志断点的时间。

3.2 端侧 Server 连一个怎么配：Streamable HTTP 传输

MCP 目前推荐的 HTTP 传输是 Streamable HTTP，它相比早期版本的 HTTP+SSE，最大的变化是支持在同一个端点平滑处理 GET、POST、DELETE 请求，会话管理也更简单。

下面是在 Node 环境注册一个基于 Express 的 MCP HTTP 服务的完整最小示例：

import express from "express"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; const app = express(); app.use(express.json()); const server = new McpServer({ name: "mobile-mcp", version: "0.1.0" }); server.registerTool( "send_notification", { title: "发送本地通知", description: "在手机设备上显示一条系统通知", inputSchema: { type: "object", properties: { title: { type: "string" }, body: { type: "string" }, vibrate: { type: "boolean", default: false } }, required: ["title", "body"] } }, async (params) => { // 此处映射到原生通知模块 return { content: [{ type: "text", text: "通知已发送" }] }; } ); let transport; app.post("/mcp", async (req, res) => { transport = new StreamableHTTPServerTransport({ sessionIdGenerator: req.body.method === "initialize" ? undefined : undefined }); res.on("close", () => {}); await server.connect(transport); await transport.handleRequest(req, res); }); app.listen(3000);

这段代码需要注意：StreamableHTTPServerTransport每次初始化时会生成Mcp-Session-Id，如果复用同一个 transport 变量，断线重连时会出现 session 不存在的报错。正确的做法是建立 session 映射表，用收到的Mcp-Session-Id找到对应 transport 实例再处理请求。

3.3 把手机摄像头变成工具：一个完整示例

我们来看一个更实际的例子：把“拍照”封装成一个 MCP 工具。这个工具在设备端会做三件事：申请相机权限、拉起拍照 UI、把拍到的照片保存到本地，然后返回图片路径和缩略图描述给模型。

注册工具时，schema 设计如下：

server.registerTool( "capture_photo", { title: "拍照", description: "调用手机摄像头拍照，返回图片路径和基础信息", inputSchema: { type: "object", properties: { purpose: { type: "string", description: "拍照用途，用于权限提示说明" }, returnBase64: { type: "boolean", default: false } }, required: ["purpose"] } }, async (params) => { const granted = await requestCameraPermission(params.purpose); if (!granted) { return { content: [{ type: "text", text: JSON.stringify({ code: "PERMISSION_DENIED" }) }], isError: true }; } const photo = await nativeBridge.capturePhoto(); return { content: [{ type: "text", text: JSON.stringify({ path: photo.path, width: photo.width, height: photo.height, size: photo.size }) }] }; } );

这里的重点是purpose参数。移动端系统在首次弹权限框时必须说明用途，如果调用时没有这个信息，只能硬编码一句笼统的“App需要相机权限”，用户一看就不想给。把模型的意图（比如“帮我把桌上文档拍下来”）提取成用途文案，授权通过率会明显好很多。

3.4 内嵌 Host 怎么连远程 MCP Server

如果你的模型跑在云端，手机端只需要作为 Host 连接远程 MCP Server，那过程更轻量。用官方 SDK 里的Client类：

import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const client = new Client({ name: "mobile-host", version: "0.1.0" }); const transport = new StreamableHTTPClientTransport({ requestUrl: "https://your-mcp-server.example.com/mcp", sessionId: restoredSessionId // 关键：恢复持久化的 session }); await client.connect(transport); const tools = await client.listTools(); console.log(tools);

移动端这里最值得注意的就是sessionId的恢复。如果网络切换后 session 失效，服务端会返回 400 或 404。此时你需要重新初始化会话，并考虑是否要重置上下文。我在 Host 层做了个简单策略：如果连接恢复后 session 已失效，先尝试向模型发送一条“上下文可能丢失”的提醒，避免模型在缺失历史的情况下执行高风险操作。

3.5 鉴权与密钥管理：别把 Token 写进 App

MCP 协议对于远程 Server 的鉴权标准是 OAuth 2.1，但目前各个实现程度参差不齐。在 mobile-mcp 项目里，我采取了一套更务实的做法：如果远程 Server 是我们自己控制的，就直接用短时 Bearer Token；如果对接第三方服务，则走 MCP 官方支持的标准 OAuth 流程。

但不管你选哪种，密钥绝不能硬编码进移动端包里。应用包拿出去逆向一翻，密钥就漏了。我的方案是：把 Token 放到 Keychain（iOS）/ Keystore（Android），首次登录后从服务端换发短期 Token，并且每次启动时校验有效期。如果 Token 过期，Host 端维护一个刷新队列，先让后续请求处于 pending 状态，等待刷新完成再放行。

4. 常见问题与排查实录

4.1 传输层选型对比：stdio、HTTP 还是 WebSocket

MCP 的传输方式在不同环境下表现差异很大。我实测下来，在移动端最实用的还是 Streamable HTTP。

自己在电脑上调试用 stdio，到了手机上老老实实用 HTTP。我在项目早期试过在 React Native 里跑 stdio，结果发现 RN 的 Polyfill 对子进程支持是个大坑，光解决process.stdin的兼容问题就花了两天，最后全砍了换 HTTP。这里给后来者一个忠告：不要在移动端折腾 stdio，就算能跑也会被系统生命周期搞得痛不欲生。

4.2 网络切换和后台冻结的五个必踩坑

移动端联调时最烦的就是网络问题。我列一下最容易踩的坑：

• Wi-Fi 切蜂窝：TCP 连接直接断，Streamable HTTP 的 POST 流也会中断。解决方案：监听网络变化事件，主动调用 transport 的 reconnect，并携带旧的 Session ID。
• IP 变化导致回话地址失效：如果你的 MCP Server 部署在局域网，网段一变就全断。建议远程 Server 一律用域名 + HTTPS，避免 IP 直连。
• iOS ATS 限制：默认禁止 HTTP 明文请求，如果你测试时用http://192.168.x.x，必须在 Info.plist 里做本地网络声明和 ATS 例外，否则接口直接黑屏。
• 后台推送唤醒：如果你的工具包括“定时拉取天气并发通知”，不能指望 App 一直活着。我最后的方案是走系统推送通道在后台唤醒处理，用完立刻释放进程。
• Android 的电池优化白名单：重要 MCP Server 服务需要引导用户把应用加入白名单，否则锁屏十分钟后必被冻结。

4.3 JSON Schema 复杂度和模型调用成功率

这是我在项目里实验性总结出的一个经验规律：模型调用工具的成功率，和输入 Schema 的复杂度呈反比。特别是嵌套allOf、anyOf、多层级required时，模型经常产出非法 JSON。我的建议是：每个工具的输入参数控制在 6 个以内，所有字段使用最基本的类型（string、number、boolean），不要用 enum 超过 5 个选项，不要搞oneOf这种抽象结构。如果你实在需要多种调用形式，拆成两个工具来设计，比让模型去理解复杂 schema 可靠得多。

可以在 Server 端做一层“Schema 预校验”：在真正执行工具前，用ajv或zod校验模型传入的参数，不合法直接返回错误码，例如INVALID_PARAMS，并告诉模型具体是哪个字段不合法。模型下一轮就能根据反馈自纠，成功率会高不少。

4.4 权限弹窗连续触发：用户体验的崩盘点

移动端最容易让用户体验崩掉的一个场景是：模型连续调用三个高敏感工具，导致系统权限弹窗一个接一个弹出来。比如用户说“帮我把当前位置发给正在开会的同事，并拍一张现场照片”，Host 触发定位权限、通讯录权限、相机权限，三个弹窗先后出现，任何正常人都会烦躁。

我的解法是在权限控制器里加了“弹窗合并”策略：一段时间内的多个敏感工具请求会排队，最多只弹一个弹窗，等到当前请求有了结果之后，再弹下一个。同时在界面交互上，给用户一个“本次会话允许”的粒度选项，而不是每次都弹系统框。这实际上是在系统的“一次性授权”和“永久授权”之间增加了一个动态档位，比较符合移动端直觉。

4.5 工具执行结果的“大块内容”处理

有些工具返回值很大，比如读取一个 20MB 的 PDF、或者扫描整个相册的缩略图。直接把全部内容塞进content返回给模型，不仅容易把上下文塞爆，模型也理解不了。我的办法是对输出做“分层摘要”：先返回元数据和摘要，具体内容由模型决定是否继续读取。这样既不会丢掉信息，又能在 token 约束内完成交互。以文件读取为例，返回字段就带uri、size、mimeType、excerpt四项，模型如果需要更多，可以调用read_file_segment工具按偏移量读。

这个设计其实和 MCP Resources 的延迟加载思路是同构的，工具调用本身也可以这样。移动端的内存和流量都宝贵，别学桌面端那种“拿过来再说”的风格。

5. 后续还能往哪走：端侧模型 + MCP 的组合

工具跑通之后，我最大的感受是，移动端 MCP 真正有潜力的方向是配合端侧小模型，做一个完全离线的个人助手。手机上的 MCP Server 把本地所有能力统一暴露给端侧模型，模型在本地完成工具调用和决策，数据不出设备，延迟又低，隐私问题也被绕过去了。我在一台中端 Android 机上做过实验，端侧模型加 mobile-mcp 的延迟大概在 800 毫秒到 2 秒之间，虽然不能和大云端比，但日常场景已经够用。

另外可以考虑把移动设备作为“边缘 MCP 网关”，向家中的其他设备（智能家居、路由器、电视盒子）暴露操作能力。手机在这里既不完全是 Host，也不完全是 Server，更像一个可移动的控制面。这类玩法目前文档和最佳实践都还很少，但方向很值得关注。

最后分享一个我个人的体会：做 mobile-mcp 这类项目，最忌讳一开始就想着做全。先把“通知 + 位置 + 拍照”三个工具跑通，能在一个真实对话里被模型连续调用，就已经算成功了一大半。后续要加新能力，基本都是按模式复制，架构不会变。MCP 的设计初衷本是解耦，但移动端接入时最重要的反而是控制耦合边界——哪些工具永远在端上，哪些工具走远程，这个边界想清楚，整个项目的气质就稳了。