在MCP支付流程里agent能不能走到最后一步往往不取决于模型能力而取决于业务流程是否允许“人不在场”时继续推进。最典型的问题是agent已经创建了支付订单但流程需要signer签名者/授权人确认而signer可能不在线、设备离线、或者根本没有收到通知agent又无法替代signer完成签名。于是支付流程卡在AWAITING_SIGNER后续步骤全部暂停。这个问题不是单一代码 bug而是把“人类审批环节”错误地设计成了agent可以同步完成的步骤。下面会从MCP协议中的角色关系出发拆解一个支付流程中signer不可达的场景给出状态机设计、MCP Server工具设计、Python最小可运行示例以及排查和落地建议。整个内容围绕一条主线当agent无法触达signer时流程应该怎么设计才既不会卡死也不会被agent绕过。1. 先理解MCP支付流程里agent、signer和工具的关系1.1 MCP是让agent访问外部工具的标准协议MCPModel Context Protocol解决的核心问题是模型如何稳定、统一地调用外部数据源和工具。没有MCP时agent要对接支付系统、订单系统、消息通知系统往往需要为每个接口写一套自定义调用逻辑有了MCP之后这些能力被封装成MCP Server工具agent通过MCP Client调用。在支付场景里MCP Server通常封装的是支付平台、订单系统、通知系统的接口。一次完整的支付并不是模型自己完成的而是模型根据业务规则编排多个工具调用最终由支付服务完成资金操作。这里要特别明确MCP只是工具调用协议它不改变资金流程的责任边界。1.2 signer为什么是支付流程的关键节点支付往往需要授权。这里的signer宽泛指“有权对这笔交易做最终确认的人”可能是一个审批人、财务人员也可能是持卡人或企业管理员。在部分流程里signer需要输入密码、验证码甚至完成一次数字签名。只要有signer存在流程就变成了“agent 人工异步审批”的混合流程。agent可以创建订单、发送通知、查询状态但签名动作必须由人完成。如果系统允许agent替代signer确认签名那么在合规和安全上都会出问题。这也解释了为什么“agent无法触达signer”是一个必须被认真处理的业务状态而不是可以强行绕过的异常。1.3 “agent无法触达signer”到底意味着什么无法触达不是一次简单的网络请求失败而是agent在有效时间内没有从signer那里获得确认。常见情况包括signer不在线设备离线。通知渠道失败短信、推送或站内信没有送达。签名服务返回SIGNER_UNREACHABLE。signer收到了通知但没有处理。signer点击后拒绝签名。签名链接或会话已过期。在MCP架构里agent调用工具后拿到的是结果对象。它需要区分“业务无法完成”和“技术调用失败”是两回事。技术调用失败是MCP Server本身出错业务无法完成是signer还没有做出决定。这两者的重试策略、告警级别和人工介入方式完全不同。表现类型判断依据MCP Server连接超时技术异常返回异常或timeout工具返回SIGNER_UNREACHABLE业务状态返回结构化字段statussigner已读但未操作人工延迟signer侧提供状态signer拒绝签名业务结束状态变为REJECTED签名链接过期人工未响应状态变为EXPIRED1.4 核心设计原则把“人的判断”和“机器的判断”分开agent负责创建支付、检查状态、触发提醒。signer负责授权。agent可以判断signer当前不可达但不能替signer签名。所以在设计流程时要把状态机独立出来让流程可以在AWAITING_SIGNER状态下等待并决定何时超时、何时重试、何时转人工。实际项目中常见的一个错误做法是让agent循环调用“获取签名结果”直到成功失败就继续问。这会把一个异步人工流程变成一个同步等待流程不仅浪费上下文也会让agent在signer长时间不回复时陷入无限循环。正确的做法是agent只负责发起和查询真正等待和确认的职责由业务流程承担。2. 设计一个最小MCP支付流程状态机、工具和调用顺序2.1 用状态机描述支付流程支付流程要可恢复就必须有明确的订单状态。一个最小状态集合可以这样设计状态含义下一步动作CREATED订单创建成功通知signerAWAITING_SIGNER已通知signer等待确认轮询或等待回调SIGNER_UNREACHABLE无法触达signer重试或转人工SIGNED签名完成执行后续支付动作REJECTED签名者拒绝关闭订单EXPIRED超过有效期关闭订单FAILED系统或流程失败退款或人工处理为什么不能只有“成功”和“失败”两个状态因为在支付场景中signer可能几分钟后才回复系统需要在这段时间里保存中间状态。如果agent调用临时中断或者MCP Server重启只要订单状态持久化了流程就能恢复。没有中间状态就会丢失进度甚至造成重复支付。2.2 MCP Server需要提供的工具针对上述状态MCP Server可以暴露如下工具create_payment(order_id, amount, signer_id)创建支付订单。notify_signer(order_id)向signer发送签名请求。get_payment_status(order_id)查询当前状态。confirm_signing(order_id, signature)由signer侧调用的确认接口。cancel_payment(order_id)取消订单。simulate_signer_online(signer_id, online)demo用用来模拟signer在线或离线。工具命名可以根据实际业务调整但需要保证返回结果是结构化JSON。不要只返回“成功”或“失败”字符串因为agent要靠status字段做分支判断。例如notify_signer需要返回{ status: SIGNER_UNREACHABLE, order_id: PO-1001, message: signer offline }这样agent才能读取status并决定下一步是重试、转人工还是取消。2.3 调用顺序与轮询策略agent侧的标准调用顺序是create_payment创建订单。notify_signer请求签名。get_payment_status轮询订单状态。如果状态是SIGNED进入后续流程如果是SIGNER_UNREACHABLE按策略重试如果重试耗尽转人工。轮询之间要加延迟不能死循环。推荐使用指数退避第一次等2秒第二次等4秒第三次等8秒最多等10秒或固定上限。这样既能给signer留出反应时间又不会在MCP Server上造成持续高频请求。2.4 为什么不能让agent直接等待signerLLM调用MCP工具时一次会话有上下文窗口限制和运行时间限制。如果agent一直轮询等待不仅占用上下文还可能在signer迟迟不回复时让整个agent会话崩溃。更糟糕的是如果同一时间有多个支付订单等待签名agent无法同时保持所有等待状态。正确的做法是把流程外置支付订单状态保存在数据库signer确认后由外部事件触发后续动作agent只负责发起和查询。这样才能做到“agent可以失败流程不能丢”。3. 用Python FastMCP实现一个可运行的signer不可达demo3.1 环境准备下面的示例基于MCP Python SDK不同版本API略有差异落地前先确认你实际安装的版本。学习环境可以使用Python 3.10以上并用虚拟环境隔离依赖。环境项建议用途Python3.10运行MCP SDKmcp最新稳定版提供FastMCP和ClientSession安装工具pip或uv管理依赖数据库暂不需要demo使用内存字典安装依赖python -m venv .venv source .venv/bin/activate pip install mcp[cli]如果网络环境里安装MCP库不顺利可以先确认Python版本和pip源。这个demo不引入额外数据库只用来演示流程和状态设计。3.2 项目结构payment_mcp_demo/ ├── payment_server.py ├── agent_client.py └── README.mdpayment_server.pyMCP Server承载支付工具。agent_client.pyMCP Client模拟agent调用工具。README.md记录运行命令和状态说明。这是最小结构。生产环境会多出数据库、消息队列、通知服务等模块。3.3 MCP Server代码下面代码使用FastMCP定义支付相关工具。signer在线状态先用全局字典模拟真实项目可以替换为查询外部设备状态或通讯录状态。# payment_server.py from mcp.server.fastmcp import FastMCP import time mcp FastMCP(payment-flow-demo) # 学习环境使用内存字典保存订单 orders {} # signer在线状态模拟真实项目可以替换为外部服务 signer_online { signer_001: True, signer_002: False, } mcp.tool() def create_payment(order_id: str, amount: float, signer_id: str) - dict: orders[order_id] { order_id: order_id, amount: amount, signer_id: signer_id, status: CREATED, error: , updated_at: time.time(), } return {status: OK, order_id: order_id, amount: amount} mcp.tool() def notify_signer(order_id: str) - dict: order orders.get(order_id) if not order: return {status: ERROR, message: order not found} signer_id order[signer_id] if not signer_online.get(signer_id, False): order[status] SIGNER_UNREACHABLE order[error] signer offline return { status: SIGNER_UNREACHABLE, order_id: order_id, message: signer offline, } order[status] AWAITING_SIGNER order[error] return { status: AWAITING_SIGNER, order_id: order_id, message: notification sent, } mcp.tool() def get_payment_status(order_id: str) - dict: order orders.get(order_id) if not order: return {status: ERROR, message: order not found} return { order_id: order_id, status: order[status], error: order[error], } mcp.tool() def confirm_signing(order_id: str, signature: str) - dict: order orders.get(order_id) if not order: return {status: ERROR, message: order not found} # 允许从等待中或不可达状态恢复保证signer晚回复也能继续 if order[status] not in (AWAITING_SIGNER, SIGNER_UNREACHABLE): return {status: ERROR, message: invalid status for signing} order[status] SIGNED order[signature] signature order[error] return {status: SIGNED, order_id: order_id} mcp.tool() def simulate_signer_online(signer_id: str, online: bool) - dict: signer_online[signer_id] online return {status: OK, signer_id: signer_id, online: online} if __name__ __main__: mcp.run()这段代码有四个关键点使用内存字典保存订单只适合学习环境。notify_signer返回SIGNER_UNREACHABLE而不是抛异常。confirm_signing允许从SIGNER_UNREACHABLE状态执行因为signer可能晚回复。simulate_signer_online专门用于模拟不可达场景。3.4 查看工具定义和调试FastMCP启动后可以利用MCP内置调试能力查看工具列表。如果你使用的是带CLI的MCP包可以先运行python payment_server.py然后在另一个终端执行MCP Client连接。也可以直接在项目里写一个最简client来调用。3.5 MCP Client/Agent调度代码agent侧使用MCP Python SDK连接stdio server。下面的agent_client.py演示了创建订单、通知signer、查询状态的完整过程。# agent_client.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params StdioServerParameters( commandpython, args[payment_server.py], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # 1. 创建支付订单 result await session.call_tool( create_payment, { order_id: PO-1001, amount: 199.0, signer_id: signer_001, }, ) print(create_payment:, result) # 2. 通知签名者signer_001默认在线 result await session.call_tool( notify_signer, {order_id: PO-1001}, ) print(notify_signer:, result) # 3. 查询状态 result await session.call_tool( get_payment_status, {order_id: PO-1001}, ) print(get_payment_status:, result) if __name__ __main__: asyncio.run(main())运行方式python agent_client.py预期输出里能看到CREATE、AWAITING_SIGNER、以及最后的订单状态。注意不同MCP SDK版本返回结果的字段结构可能不同实际项目里要写一个统一的结果解析函数。3.6 模拟signer不可达把agent_client.py改造成先让signer_002离线再触发notify_signerawait session.call_tool(simulate_signer_online, {signer_id: signer_002, online: False}) result await session.call_tool(create_payment, {order_id: PO-1002, amount: 99.0, signer_id: signer_002}) result await session.call_tool(notify_signer, {order_id: PO-1002}) print(result)预期返回{ status: SIGNER_UNREACHABLE, order_id: PO-1002, message: signer offline }拿到这个结果后agent就应该进入重试或转人工逻辑而不是继续死等。4. 当agent拿不到signer时重试、降级和人工通道4.1 不要把SIGNER_UNREACHABLE当异常在MCP工具设计里SIGNER_UNREACHABLE是一个业务状态不是技术异常。它和“MCP Server连接失败”完全不同。业务状态应该结构化返回让agent可以读取并选择策略。如果工具直接抛异常模型可能只会看到一条错误信息无法区分“signer不在线”和“系统崩溃”自然也就无法决定是重试还是转人工。真实项目中建议在工具返回里始终包含status、order_id、message三个字段并保持status枚举固定。这样agent可以针对固定枚举做分支判断。4.2 重试策略有限次数 指数退避一个实用的重试逻辑是async def try_notify_signer(session, order_id, max_retries3): for attempt in range(1, max_retries 1): result await session.call_tool(notify_signer, {order_id: order_id}) status extract_status(result) if status ! SIGNER_UNREACHABLE: return result wait_time min(2 ** attempt, 10) print(fattempt {attempt}: signer unreachable, wait {wait_time}s) await asyncio.sleep(wait_time) return {status: NEED_MANUAL, message: retry exhausted}这里的关键是必须设置上限。没有上限的重试会造成通知风暴也可能让agent在无效等待中耗尽执行时间。指数退避的目的是前几次重试间隔短一点给临时离线留恢复机会后几次间隔变大避免持续打扰。还要注意一点重试的是“通知signer”不是“伪造signer确认”。如果signer始终不可达任何重试都不能让签名完成最终一定要走到人工通道。4.3 降级为人工状态落地 通知运营人员当重试耗尽agent无法完成支付系统要给人一个明确出口。可以把订单状态改成NEED_MANUAL并写入一条事件记录。生产环境里这个事件可以触发工单系统、发送给运营人员或者进入人工审批队列。这里特别要强调agent不能为了完成任务而绕过signer。在资金操作场景中绕过签名直接放行是严重的合规风险。即使agent给出了看似合理的解释系统也必须在架构上禁止这种路径。所以人工通道不是可选优化而是支付流程的兜底必备项。4.4 如果signer后来上线了怎么办signer不可达并不是永久状态。可能几分钟后signer重新上线收到了通知完成了签名。这时候订单还停留在SIGNER_UNREACHABLE或NEED_MANUALconfirm_signing工具必须允许从这些状态流转到SIGNED。这就是状态机设计里“恢复能力”的价值。如果agent已经退出了本次会话后续流程可以由外部事件继续。比如signer确认后支付服务收到回调将订单从SIGNED推进到下一步。agent之后再来查询看到的是最终状态而不需要重新执行整个流程。4.5 上下文过大和agent终止的关联如果在长会话里agent把每一次工具调用的完整结果都塞进上下文很快就会触发上下文过大。很多MCP集成报错“上下文过大”或“agent terminated due to error”不是因为模型不会用工具而是因为业务状态没有外置不得不依赖会话历史。支付流程尤其要避免这种情况。正确做法是让agent每次只查询一次get_payment_status拿到当前状态后就结束不要把create_payment、notify_signer、get_payment_status的完整JSON都保留在上下文。状态存数据库上下文只留摘要。5. 验证与排查从一条SIGNER_UNREACHABLE记录找到根因5.1 可观测性每条状态流转都要有日志和事件生产环境要能回答“这笔订单现在卡在哪一步为什么卡住”。所以MCP Server端要在每个工具调用前后打印日志client端要记录agent的决策链。建议日志像下面这样[payment-server] call create_payment {order_id: PO-1001, signer_id: signer_001} - OK [payment-server] call notify_signer {order_id: PO-1001} - SIGNER_UNREACHABLE, reason: signer offline [agent] retry 1/3 after 2s, order: PO-1001 [agent] retry exhausted, order: PO-1001 - NEED_MANUAL日志里不要记录完整签名避免敏感信息泄露。5.2 排查链路从现象倒推根因当出现“agent cant reach signer”时按下面顺序排查确认调用的MCP Server是哪个环境、哪个版本。检查signer在线状态表或设备状态。确认通知渠道是否返回成功回执比如短信、推送、站内信。查看MCP Server日志里notify_signer的调用时间和返回结果。检查agent上下文是否已经过大导致没有空间处理返回结果。检查重试逻辑是否有上限是否误把业务状态当技术异常处理。5.3 常见错误和解决方案问题现象常见原因检查方式处理建议agent一直在notify_signer重试没有上限查看agent日志调用次数增加最大重试次数和退避时间signer已确认但流程仍卡住confirm_signing不允许从SIGNER_UNREACHABLE流转检查状态机流转条件允许从不可达状态恢复工具返回SIGNER_UNREACHABLEagent把它当异常处理业务状态建模错误查看异常处理逻辑改为结构化返回区分业务状态agent重启后订单状态丢失状态只存在内存或上下文检查存储使用数据库保存订单状态上下文过大导致agent终止每次调用完整结果都保留查看上下文占用只保留状态摘要状态外置5.4 可复用排查清单在发布支付MCP流程前建议逐项检查[ ] 是否确认signer身份和在线状态[ ] 通知渠道是否返回成功回执[ ] 工具返回是否区分业务不可达和系统异常[ ] 是否有重试上限和退避时间[ ] 重试耗尽后是否有人工介入入口[ ] 订单状态是否保存在外部存储而不是agent上下文[ ] signer确认接口是否幂等[ ] 是否设置签名链接过期时间[ ] MCP Server日志是否记录每次调用入参和出参[ ] 生产环境是否对SIGNER_UNREACHABLE添加监控告警6. 生产环境落地建议与扩展方向6.1 学习环境与生产环境的差异上面的demo用内存字典保存订单用全局字典模拟signer在线状态这足够用来理解流程。生产环境会有明显差异维度学习环境生产环境订单存储内存字典数据库消息通知直接调用函数短信、推送、站内信、消息队列状态恢复重启即丢失数据库持久化 定时任务幂等控制不需要必须支持安全审计无完整记录操作日志并发单进程多实例 分布式锁监控无日志、指标、告警6.2 安全和合规要点支付相关系统需要对MCP Server暴露的工具做权限控制。不是所有agent都能执行create_payment和confirm_signing。至少要做身份认证、角色授权、操作审计。签名值绝不能写成明文日志。金额和订单状态变更要留审计记录。涉及资金操作时建议使用独立签名服务并做二次确认。agent可以请求签名但最终执行支付必须以签名服务的成功回调为准不能以agent自己的判断为准。6.3 交互模式扩展可以让流程从“agent轮询”升级为“事件回调”。signer确认后通过webhook通知支付服务或agent的宿主系统避免反复轮询。也可以增加二维码和移动端推送signer收到二维码后扫码确认agent只需要维护订单状态不参与签名页面渲染。多级审批场景下状态机要增加等待多个signer的节点所有signer都确认后才能执行支付。6.4 对新手的练习建议先把上面的demo跑通然后把内存字典改成SQLite或PostgreSQL再加入一个模拟消息队列最后把notify_signer改为真实短信或推送接口。做完这三个改造后再思考一个问题如果重试耗尽后signer又上线并完成了签名系统如何保证不会重复支付能把这个问题回答清楚你对MCP支付流程的理解就不再停留在工具调用层面而是真正进入了状态机、幂等和人工兜底的设计层面。
