Remote MCP 指南

晓鹜开放平台的接入、提交与私有结果。

Remote MCP 手册

将 MCP 客户端连接到远程服务。本手册覆盖客户端配置、暴露的工具以及付费调用的重试规则。

01

连接客户端

在客户端中配置 HTTPS MCP 端点与请求级 API 密钥。替换本地配置中的源地址与密钥占位符。

mcp-connect复制mcp-connect 示例
{
  "mcpServers": {
    "matwingsvenus": {
      "url": "https://YOUR_PLATFORM/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
02

凭证与作用域

每次请求使用各自的凭证。每个密钥属于一个账户。远程工具白名单不包含密钥管理、密码、支付与运营操作。

mcp-credentials复制mcp-credentials 示例
Transport    Remote MCP over HTTPS
Credential   Account API key per request
Endpoint     /mcp
Account      Shared files, jobs, balance and quotas
03

发现工具与价格

付费调用前先使用服务的发现与报价工具。阅读已发布的输入与结果契约;智能体不能选择执行器或运行时命令。

mcp-discover复制mcp-discover 示例
list_tools
get_tool
create_quote
get_balance
list_files
04

提交付费任务

用稳定的 submission_key 调用 mcp_submit_job。重试时保留原始参数。省略可选的授权金额即使用账户默认值。

使用下方示例中完整、固定版本的 mcp_submit_job 参数,包括 READY 文件变体。凭证放在传输头中,绝不放入工具参数。

05

跟踪并读取结果

用受理返回的任务 ID 查询状态、结构化结果与输出下载请求。显式读取私有结果。MCP 文件输入引用你自己的 READY 文件 ID。

mcp-results复制mcp-results 示例
list_jobs
get_job
get_job_result
get_job_output_download
06

安全重试与取消

响应不确定后,用相同的 submission_key 与参数重试以恢复原任务。用 cancel_job 请求停止。原结果未知时不要提交替代任务。

mcp-retry复制mcp-retry 示例
mcp_submit_job   Reuse original submission_key and arguments
cancel_job       Request cancellation of the accepted job
get_job          Wait for confirmed outcome
07

限制与隐私

智能体不能提高已受理的授权上限,也不能访问其他账户的资源。输入与结果保持私有,不用于训练。过期内容返回 410;有效的空结果含义不同。

账户统计使用 /developers/api#usage 中描述的 REST 用量与消费报表。创建期间费用不同于结算期间消费;当前余额与活跃是独立快照。null、零与未核实用量始终区分。MCP get_usage 保留原参数与响应字段;新的 REST 报表路由不是 MCP 工具。

mcp-limits复制mcp-limits 示例
Allowed       Published compute tools and owned resources
Not exposed   Keys, passwords, payment writes, operations
Paid retries  Same stable submission_key

完整示例:蛋白性质

protein_properties_physicochemical@2026-10-14-candidate

正在检查该示例版本当前是否已发布…

用途与输入规则

从一条蛋白序列计算理化特征:长度、分子量、理论 pI 与氨基酸组成,以 JSON 返回。

该版本只返回理化特征,不生成蛋白结构,也不输出文件。公开示例是教学材料,不是一次新的计算,也不构成质量评估。

  • sequence 与 fasta_file 必须且只能提供一个;另一个请省略或设为 null。同时提供或都不提供都会被拒绝。
  • sequence 不能为空,且只能使用大写 ACDEFGHIKLMNPQRSTVWY。FASTA 必须包含一条非空序列并使用同一字母表;包含多条记录会被拒绝。
  • task_name 固定为 Physical and chemical properties。省略时使用默认值,或按原样传入该常量;不支持其他任务。
  • fasta_file 请使用属于本账户且状态为 READY 的文件。接受的格式为 fasta、fa 与 faa。本地路径不是 file_id。
  • 工具输入上限为 134217728 字节。直接提交 JSON 任务(含元数据)上限为 131072 字节(128 KiB)。序列更大时请改用文件上传与 READY 引用。结构化结果上限为 65536 字节。

版本 2026-10-14-candidate。将下方完整公开请求体保存为 request.json。

将 MATVENUS_API_URL 设为你的 HTTPS 平台基础地址,并把 MATVENUS_API_KEY 放在受保护的环境中(或使用已有 CLI 登录)。为这个逻辑任务设置新的唯一 SUBMISSION_KEY;重试时保留同一密钥与完全相同的请求。新任务需要新密钥。

request.json复制公开序列请求
{
  "tool_id": "protein_properties_physicochemical",
  "tool_version": "2026-10-14-candidate",
  "parameters": {
    "sequence": "ACDEFGHIKLMNPQRSTVWY"
  }
}

Remote MCP

将 MCP 客户端连接到平台 HTTPS /mcp 端点,并在每次请求中带上 Authorization: Bearer 与你的 API 密钥。用下方参数调用 mcp_submit_job;这些是客户端工具参数,不是 HTTP 请求体。将提交密钥占位符替换为你保留的密钥。

mcp_submit_job · arguments复制MCP 提交参数
{
  "tool_id": "protein_properties_physicochemical",
  "tool_version": "2026-10-14-candidate",
  "parameters": {
    "sequence": "ACDEFGHIKLMNPQRSTVWY"
  },
  "submission_key": "REPLACE_WITH_THIS_LOGICAL_JOB_KEY"
}

将 job_id 设为提交返回的 id。反复调用 get_job 直到 SUCCEEDED,再调用 get_job_result。下方代码块展示你的 MCP 客户端需要的工具名与参数。

get_job · arguments复制MCP 状态参数
{
  "job_id": "RETURNED_JOB_UUID"
}
get_job_result · arguments复制MCP 结果参数
{
  "job_id": "RETURNED_JOB_UUID"
}

HTTP 202 表示已受理。即使客户端超时也请保留 Job ID。结果未就绪时返回 409,删除或过期后返回 410。失败或取消的任务可能没有结果。冲突重试返回 409;请检查原任务而非重新提交。

改用 FASTA 文件

将这份公开单记录样本保存为 public-sample.fasta,通过 REST 或 CLI 上传;MCP 不能上传二进制文件。确认返回的文件属于你的账户且状态为 READY。

此处展示的预期 JSON 对应直接序列输入,其 sequence_id 为 temp_sequence。使用 FASTA 输入时,sequence_id 来自记录头;本示例 FASTA 使用 public-sample。序列标识与平台任务 ID 是两回事。

public-sample.fasta复制公开 FASTA 样本
>public-sample
ACDEFGHIKLMNPQRSTVWY

先执行上传命令,再将 FILE_ID 设为返回的 id,并确认文件状态为 READY。

REST · upload and check READY复制REST 文件上传
curl --silent --show-error --fail-with-body \
  -H "Authorization: Bearer $MATVENUS_API_KEY" \
  -F "file=@public-sample.fasta" -F "purpose=input" "$MATVENUS_API_URL/v1/files"
curl --silent --show-error --fail-with-body \
  -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/files/$FILE_ID"
CLI · upload and check READY复制CLI 文件上传
matvenus --json files upload ./public-sample.fasta
matvenus --json files show "$FILE_ID"

将文件 ID 占位符替换为该 READY 的 UUID,再存为 request.json 并用上面的 REST 或 CLI 步骤提交。这个不同的逻辑任务需要使用新的提交密钥。此时省略 sequence。

request.json · READY file variant复制就绪文件请求
{
  "tool_id": "protein_properties_physicochemical",
  "tool_version": "2026-10-14-candidate",
  "parameters": {
    "fasta_file": {
      "file_id": "REPLACE_WITH_READY_FILE_UUID"
    }
  }
}

使用 MCP 时,请改用下面这个完整的 mcp_submit_job 参数对象:

mcp_submit_job · READY file arguments复制MCP 就绪文件参数
{
  "tool_id": "protein_properties_physicochemical",
  "tool_version": "2026-10-14-candidate",
  "parameters": {
    "fasta_file": {
      "file_id": "REPLACE_WITH_READY_FILE_UUID"
    }
  },
  "submission_key": "REPLACE_WITH_THIS_LOGICAL_JOB_KEY"
}
公开样本来源

仓库中的版本化材料;这些样本不能证明工具当前可用,以启用目录为准。

  • worker_groups/protein-properties-physicochemical/candidate-contract.jsonSHA-256: 17f0d36cc81729a3dcf225813df8253213faf19905ec99409962d1d33632497e
  • worker_groups/protein-properties-physicochemical/public/sequence-request.jsonSHA-256: 83bbe6829d85d48aa0446a8646232b97012af7d058707a232c9057f7b1a1abe4
  • worker_groups/protein-properties-physicochemical/public/expected-sequence-result.jsonSHA-256: 0353c5c39d8d9a9f0ae278655ba536f99611e112a41d3a064d8df885b76cb7f2
  • worker_groups/protein-properties-physicochemical/public/public-sample.fastaSHA-256: 27b4df93ee69cfe9d6d92bc808a99f21a8272c20b3daab602138ec0d94e5df83

理解 JSON 结果

公开序列的完整预期输出。这是已存储的公开样本,不是本页面执行的计算。该版本没有输出文件。

expected-sequence-result.json复制公开预期结果
{
  "data": {
    "sequence_id": "temp_sequence",
    "sequence_length": 20,
    "molecular_weight": 2395.71,
    "theoretical_pI": 6.78,
    "aromaticity": 0.15,
    "instability_index": 84.74,
    "gravy": -0.49,
    "secondary_structure_fraction": {
      "helix": 0.25,
      "turn": 0.25,
      "sheet": 0.35
    },
    "amino_acid_composition": {
      "A": 0.05,
      "C": 0.05,
      "D": 0.05,
      "E": 0.05,
      "F": 0.05,
      "G": 0.05,
      "H": 0.05,
      "I": 0.05,
      "K": 0.05,
      "L": 0.05,
      "M": 0.05,
      "N": 0.05,
      "P": 0.05,
      "Q": 0.05,
      "R": 0.05,
      "S": 0.05,
      "T": 0.05,
      "V": 0.05,
      "W": 0.05,
      "Y": 0.05
    }
  },
  "success": true
}
名称类型必填说明
successtrue是有效的交付结果要求 success=true 且 data 非空。空对象对该工具不是有效结果。 · 固定为 true
dataobject是不允许其他属性
data.sequence_idstring是结果中的序列标识,与平台任务 ID 不同。 · 最短长度 1
data.sequence_lengthinteger是以氨基酸残基计的序列长度。 · 最小值 1
data.molecular_weightnumber是分子量。契约未声明单位,待维护者确认。 · 大于 0
data.theoretical_pInumber是理论等电点(pI),范围 0–14。 · 0–14(含边界)
data.aromaticitynumber是芳香性数值,范围 0–1。以原始比值显示,不是百分比。 · 0–1(含边界)
data.instability_indexnumber是报告的不稳定指数;不推断稳定性评级。
data.gravynumber是报告的 GRAVY 亲水性指数;不推断质量评级。
data.secondary_structure_fraction · 3 个字段 · 必填

螺旋、转角与折叠的占比,各自 0–1。它们不必相加为 1,也不代表已生成的结构。 · 不允许其他属性

名称类型必填说明
data.secondary_structure_fraction.helixnumber是0–1(含边界)
data.secondary_structure_fraction.turnnumber是0–1(含边界)
data.secondary_structure_fraction.sheetnumber是0–1(含边界)
data.amino_acid_composition · 20 个字段 · 必填

二十种氨基酸的占比,各自 0–1。二十个字母键均为必填;0.05 表示占比 5%。 · 不允许其他属性

名称类型必填说明
data.amino_acid_composition.Anumber是0–1(含边界)
data.amino_acid_composition.Cnumber是0–1(含边界)
data.amino_acid_composition.Dnumber是0–1(含边界)
data.amino_acid_composition.Enumber是0–1(含边界)
data.amino_acid_composition.Fnumber是0–1(含边界)
data.amino_acid_composition.Gnumber是0–1(含边界)
data.amino_acid_composition.Hnumber是0–1(含边界)
data.amino_acid_composition.Inumber是0–1(含边界)
data.amino_acid_composition.Knumber是0–1(含边界)
data.amino_acid_composition.Lnumber是0–1(含边界)
data.amino_acid_composition.Mnumber是0–1(含边界)
data.amino_acid_composition.Nnumber是0–1(含边界)
data.amino_acid_composition.Pnumber是0–1(含边界)
data.amino_acid_composition.Qnumber是0–1(含边界)
data.amino_acid_composition.Rnumber是0–1(含边界)
data.amino_acid_composition.Snumber是0–1(含边界)
data.amino_acid_composition.Tnumber是0–1(含边界)
data.amino_acid_composition.Vnumber是0–1(含边界)
data.amino_acid_composition.Wnumber是0–1(含边界)
data.amino_acid_composition.Ynumber是0–1(含边界)