将 MCP 客户端连接到远程服务。本手册覆盖客户端配置、暴露的工具以及付费调用的重试规则。
连接客户端
在客户端中配置 HTTPS MCP 端点与请求级 API 密钥。替换本地配置中的源地址与密钥占位符。
{
"mcpServers": {
"matwingsvenus": {
"url": "https://YOUR_PLATFORM/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}凭证与作用域
每次请求使用各自的凭证。每个密钥属于一个账户。远程工具白名单不包含密钥管理、密码、支付与运营操作。
Transport Remote MCP over HTTPS Credential Account API key per request Endpoint /mcp Account Shared files, jobs, balance and quotas
发现工具与价格
付费调用前先使用服务的发现与报价工具。阅读已发布的输入与结果契约;智能体不能选择执行器或运行时命令。
list_tools get_tool create_quote get_balance list_files
提交付费任务
用稳定的 submission_key 调用 mcp_submit_job。重试时保留原始参数。省略可选的授权金额即使用账户默认值。
使用下方示例中完整、固定版本的 mcp_submit_job 参数,包括 READY 文件变体。凭证放在传输头中,绝不放入工具参数。
跟踪并读取结果
用受理返回的任务 ID 查询状态、结构化结果与输出下载请求。显式读取私有结果。MCP 文件输入引用你自己的 READY 文件 ID。
list_jobs get_job get_job_result get_job_output_download
安全重试与取消
响应不确定后,用相同的 submission_key 与参数重试以恢复原任务。用 cancel_job 请求停止。原结果未知时不要提交替代任务。
mcp_submit_job Reuse original submission_key and arguments cancel_job Request cancellation of the accepted job get_job Wait for confirmed outcome
限制与隐私
智能体不能提高已受理的授权上限,也不能访问其他账户的资源。输入与结果保持私有,不用于训练。过期内容返回 410;有效的空结果含义不同。
账户统计使用 /developers/api#usage 中描述的 REST 用量与消费报表。创建期间费用不同于结算期间消费;当前余额与活跃是独立快照。null、零与未核实用量始终区分。MCP get_usage 保留原参数与响应字段;新的 REST 报表路由不是 MCP 工具。
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;重试时保留同一密钥与完全相同的请求。新任务需要新密钥。
{
"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 请求体。将提交密钥占位符替换为你保留的密钥。
{
"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 客户端需要的工具名与参数。
{
"job_id": "RETURNED_JOB_UUID"
}{
"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 ACDEFGHIKLMNPQRSTVWY
先执行上传命令,再将 FILE_ID 设为返回的 id,并确认文件状态为 READY。
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"
matvenus --json files upload ./public-sample.fasta matvenus --json files show "$FILE_ID"
将文件 ID 占位符替换为该 READY 的 UUID,再存为 request.json 并用上面的 REST 或 CLI 步骤提交。这个不同的逻辑任务需要使用新的提交密钥。此时省略 sequence。
{
"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 参数对象:
{
"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: 17f0d36cc81729a3dcf225813df8253213faf19905ec99409962d1d33632497eworker_groups/protein-properties-physicochemical/public/sequence-request.jsonSHA-256: 83bbe6829d85d48aa0446a8646232b97012af7d058707a232c9057f7b1a1abe4worker_groups/protein-properties-physicochemical/public/expected-sequence-result.jsonSHA-256: 0353c5c39d8d9a9f0ae278655ba536f99611e112a41d3a064d8df885b76cb7f2worker_groups/protein-properties-physicochemical/public/public-sample.fastaSHA-256: 27b4df93ee69cfe9d6d92bc808a99f21a8272c20b3daab602138ec0d94e5df83
理解 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
}| 名称 | 类型 | 必填 | 说明 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
success | true | 是 | 有效的交付结果要求 success=true 且 data 非空。空对象对该工具不是有效结果。 · 固定为 true | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data | object | 是 | 不允许其他属性 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.sequence_id | string | 是 | 结果中的序列标识,与平台任务 ID 不同。 · 最短长度 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.sequence_length | integer | 是 | 以氨基酸残基计的序列长度。 · 最小值 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.molecular_weight | number | 是 | 分子量。契约未声明单位,待维护者确认。 · 大于 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.theoretical_pI | number | 是 | 理论等电点(pI),范围 0–14。 · 0–14(含边界) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.aromaticity | number | 是 | 芳香性数值,范围 0–1。以原始比值显示,不是百分比。 · 0–1(含边界) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.instability_index | number | 是 | 报告的不稳定指数;不推断稳定性评级。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.gravy | number | 是 | 报告的 GRAVY 亲水性指数;不推断质量评级。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.secondary_structure_fraction · 3 个字段 · 必填螺旋、转角与折叠的占比,各自 0–1。它们不必相加为 1,也不代表已生成的结构。 · 不允许其他属性
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.amino_acid_composition · 20 个字段 · 必填二十种氨基酸的占比,各自 0–1。二十个字母键均为必填;0.05 表示占比 5%。 · 不允许其他属性
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||