跳到主要内容

概述​

MCP（Model Context Protocol，模型上下文协议）是一个开放协议，让 AI 智能体（如 Cursor、Claude Code、Codex、VS Code 等客户端）通过标准化的「工具」调用外部服务的能力。对商户而言，接入 Oceanpayment MCP 后，AI 智能体即可在授权范围内查询 Oceanpayment 的账户与交易数据。

Oceanpayment MCP服务​

  • 服务端点（默认）：
https://checkout.oceanpayment.com/mcp

交易查询工具​

「交易查询」是一个只读、低风险的工具，用于分页查询当前 MCP 密钥所绑定商户与用户有权访问的正式（生产环境）交易记录，帮助智能体在商户授权范围内查询交易状态与详情，例如对账、客服排查、交易数据核对等场景。

前置条件​

在开始接入前，请确认满足以下条件：

  • 已注册 Oceanpayment 商户账户，并拥有账户后台的开发者权限（可访问「Developer → MCP 密钥管理」）；
  • 已准备一个支持远程 HTTP MCP 的 AI 客户端（如 Cursor、Claude Code、Codex、VS Code 等）；
  • 明确需要授权的工具范围（当前仅「交易查询」工具）。

MCP密钥管理​

创建MCP密钥​

MCP 密钥是 Oceanpayment MCP 的认证凭据，在账户后台创建。操作路径：登录账户后台 → Developer → MCP 密钥管理 → 创建密钥。

配置项​

创建时需配置以下内容：

配置项必填说明
密钥名称是便于识别的名称，最长 30 字符
有效期是支持 30 天 / 60 天 / 90 天 / 180 天，默认 30 天；到期需重置，实际到期时间以创建或重置成功后服务端返回时间为准
授权工具是勾选「正式交易查询」（标注：低风险、只读）；仅选择业务所需工具
注意

创建成功后，密钥仅显示一次，请妥善保存。密钥绑定当前商户与用户，智能体通过该密钥访问的即为其绑定范围之内的正式交易数据。

连接MCP Server​

端点​

在客户端中添加远程 MCP 服务时，使用以下端点：

https://checkout.oceanpayment.com/mcp

以Claude Code为例​

各客户端配置示例​

codex mcp add oceanpayment --url https://checkout.oceanpayment.com/mcp

认证与会话管理​

认证方式：MCP 密钥​

Oceanpayment MCP 采用 MCP 密钥（API Key） 认证，而非友商普遍使用的 OAuth。密钥在账户后台创建，绑定商户与用户，连接时作为认证凭据提交。以 Cursor 为例，凭据通常配置在请求头中：

{
  "mcpServers": {
    "oceanpayment": {
      "url": "https://checkout.oceanpayment.com/mcp",
      "headers": {
        "Authorization": "Bearer <您的 MCP 密钥>"
      }
    }
  }
}

密钥生命周期​

  • 密钥有效期可选 30 / 60 / 90 / 180 天，默认 30 天；
  • 到期后密钥失效，需在后台重置并更新客户端配置；
  • 密钥绑定商户与用户，访问范围即其绑定范围，建议按最小权限原则只勾选业务所需工具。

工具参考​

工具概览​

属性值
工具名称交易查询
功能描述当前 MCP 密钥绑定商户和用户有权访问的交易记录
风险等级低风险
读写类型只读

能力与限制​

  • 仅可查询正式（生产环境）交易记录；
  • 只读操作，不涉及任何资金与订单状态的变更。

安全注意事项​

  • 只读低风险：「交易查询」为只读工具，不涉及资金与订单状态变更，风险可控；
  • 密钥保密：MCP 密钥等价于账户访问凭据，请妥善保管，切勿泄露或写入代码仓库、日志等不安全位置；
  • 最小权限：仅勾选业务所需工具，避免过度授权；
  • 有效期管理：关注密钥到期时间，到期前及时重置，避免业务中断；
  • 谨慎搭配其他 MCP 服务：将 Oceanpayment MCP 与其他第三方 MCP 服务并列使用时，注意防范 prompt injection 攻击，避免恶意工具描述诱导智能体越权读取或泄露交易数据；
  • 建议开启客户端工具审批：在客户端中开启工具调用的人工确认，审查每次工具调用后再执行。