Agentic Payment MCP

代理支付验证——MCP服务器

原型 --Python 3.11·MCP SDK·Pydantic v2·pytest asyncio

问题陈述

随着支付从交易服务演变为智能代理体验，代理商务平台面临着一个结构性缺口：购物代理（LLM协调购买流程）需要启动支付操作，但收购基础设施是为人为驱动的会话身份验证请求而设计的，而不是为具有委托权限的自主AI客户端而设计的。此MCP服务器实现了弥合这一差距的验证层——在任何支付请求到达SEP（单一入口点）之前，强制执行了解你的代理（KYA）身份绑定、确定性欺诈信号评分和捕获飞行前治理。它确保人工智能发起的支付操作满足与人工发起的相同的身份、风险和监管要求，而不会在授权关键路径上增加对LLM推理的依赖。

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────────────────────────────────┐
│                            AGENTIC COMMERCE FLOW                            │
│                                                                             │
│   ┌────────────────┐     MCP Protocol     ┌─────────────────────────────┐   │
│   │ Shopping Agent │ ◄──────────────────► │   MCP Server                │   │
│   │  (LLM client)  │   stdio / HTTP+SSE   │   (this project)            │   │
│   └────────────────┘                      │                             │   │
│          │                                │  1. validate_agent          │   │
│          │  Orchestrate tool calls        │     KYA gate (15 ms)        │   │
│          │  Select next step based        │                             │   │
│          │  on tool output                │  2. check_fraud_signals     │   │
│          │                                │     Risk scoring (25 ms)    │   │
│          │                                │                             │   │
│          │                                │  3. capture_transaction     │   │
│          │                                │     Pre-flight (10 ms)      │   │
│          │                                └────────────┬────────────────┘   │
│          │                                             │                    │
│          │                                             │ SEP-formatted      │
│          │                                             │ capture payload    │
│          │                                             │ (delegated)        │
│          │                                             ▼                    │
│          │                                ┌─────────────────────────────┐   │
│          │                                │  Acquirer SEP Layer         │   │
│          │                                │  (Acquiring Infrastructure) │   │
│          │                                │  · Verifiable Intent proof  │   │
│          │                                │  · Card network routing     │   │
│          └────────────────────────────────│  · Settlement execution     │   │
│                                           └─────────────────────────────┘   │
│                                                                             │
│  ▸ The LLM orchestrates tool selection. No LLM is invoked inside tools.     │
│  ▸ Tools are deterministic, auditable, and latency-bounded.                 │
│  ▸ Session state is server-side. The client cannot skip validation steps.   │
└─────────────────────────────────────────────────────────────────────────────┘

工具顺序和延迟预算

______________________________________________________________________

设计决策

1.授权关键路径中没有LLM。 工具实现是基于规则的，在微秒内执行。\<50毫秒的SLA与LLM推理不兼容（通常为200-2000毫秒），合规审计跟踪需要可重复和可归因的决策，而不是概率性的决策。LLM作为MCP层之上的编排器运行，而不是在MCP层内部。

2.KYA的执行是服务器端的，而不是客户端的信任。 这 SessionRegistry 跟踪验证状态 session_id 在服务器上。 check_fraud_signals 和 capture_transaction 记录的KYA通行证上的两个门——客户端不能通过跳过来伪造有效的会话 validate_agent_identity。在生产环境中，此注册表由Redis支持，并在服务器实例之间共享。

3.捕获工具的设计是只读的——这是架构，而不是TODO。 该服务器是飞行前验证层。它构建了一个SEP格式的有效载荷 requires_verifiable_intent: true，但从未考虑过收购基础设施。写入执行委托给SEP，SEP在卡网络路由之前验证消费者意图的加密证明（万事达卡代理支付/Visa智能商务）。保持边界明确可以防止意外的写入路径扩展。

4.输入哈希以符合PII。 审计记录存储规范化输入字典的SHA-256摘要，从不存储原始字段值。这保留了相关性能力（相同的逻辑输入总是产生相同的哈希值），而不会在审计跟踪中暴露客户PII——这是跨境支付流中PCI-DSS和GDPR合规性的要求。

5.确定性、基于规则的欺诈评分。 五条规则，具有明确的分数贡献和因子分解。MCP工具合同(FraudSignalResult 和 risk_factors, risk_score, risk_level, recommended_action)独立于替补得分手。在生产环境中，规则引擎被从专用推理端点提供的预训练ML模型所取代——契约不会改变。

6.Pydantic v2模式作为工具契约。 AgentValidationRequest, FraudSignalRequest，以及 CaptureRequest 双重用途：运行时输入验证和JSON模式生成 list_tools()每个字段描述都是为LLM消费而编写的——模式指示代理发送什么，而不需要单独的文档。

7.MCP层幂等性。 LLM代理在不确定的情况下重试工具调用。正在进行中 _seen_idempotency_keys set（生产：Redis SET NX)在捕获请求到达SEP之前对其进行重复数据消除。这可以防止对网络模糊性的双重捕获，这是一种特定于人工驱动的支付UI不会产生的代理流的故障模式。

______________________________________________________________________

关键约束

______________________________________________________________________

本地设置

# Install (Python 3.11+ required)
git clone https://github.com/YOUR_USERNAME/agentic-payment-mcp.git
cd agentic-payment-mcp
pip install -e ".[dev]"

# Run the test suite
pytest -v

# Start the MCP server (stdio transport)
python -m src.server

服务器通过stdio与MCP通信， mcp CLI）。

______________________________________________________________________

项目结构

src/
├── server.py               # MCP server — tool registration, SessionRegistry, call_tool router
├── config.py               # Centralized constants (SLA budgets, risk thresholds, allow-lists)
├── tools/
│   ├── validate_agent.py   # KYA tool — platform check, token format, registry lookup, scopes
│   ├── check_fraud.py      # Fraud tool — 5-rule scoring engine, band mapping, session gate
│   └── capture_transaction.py  # Capture tool — 4-precondition check, SEP payload construction
├── schemas/
│   ├── agent.py            # AgentValidationRequest / AgentValidationResult
│   ├── fraud.py            # FraudSignalRequest / FraudSignalResult / RiskFactor
│   └── transaction.py      # CaptureRequest / CapturePreflightResult
└── audit/
    └── logger.py           # AuditLogger — SHA-256 input hashing, structured JSON emission

tests/
├── conftest.py             # Fixtures: fresh SessionRegistry, AuditLogger, idempotency cleanup
├── test_validate_agent.py  # 6 tests — happy path, platform/token/status failures, scope hard-fail
├── test_check_fraud.py     # 5 tests — approve path, KYA gate, cross-border, recurring, latency
└── test_capture_transaction.py  # 6 tests — full flow, KYA/fraud gates, amount mismatch, idempotency

______________________________________________________________________

这不做什么（以及为什么）

不处理实际付款。 这是飞行前验证层。真正的支付执行需要收单机构SEP集成、卡网络认证（万事达卡、Visa卡）和PCI DSS 1级合规基础设施。

不实现加密的可验证意图。 令牌验证和 requires_verifiable_intent 国旗在结构上是存在的，但被嘲笑了。生产需要与万事达卡代理支付和Visa智能商务SDK集成，以实现消费者意图证明链。

不使用ML进行欺诈评分。 规则引擎是一个结构精确的替代品 FraudSignalResult 该合同与生产机器学习记分员返回的合同相同——在不改变MCP接口的情况下，支持实现是可替换的。

不会在重新启动后保持状态。 SessionRegistry 在记忆中；审计日志仅发送到日志子系统。生产需要Redis支持的会话状态和不可变的审计日志存储（AWS QLDB、Azure不可变Blob存储）。

不实现多租户隔离。 单服务器原型。生产需要租户范围的会话命名空间、每个商家的速率限制和隔离的审计日志流。

______________________________________________________________________

堆栈

______________________________________________________________________

许可证

麻省理工学院