Connect an MCP client to the remote server. This guide covers client configuration, exposed tools and paid-call retry rules.
Connect your client
Configure the HTTPS MCP endpoint and a request-level API key in your client. Replace the origin and key placeholders in your local configuration.
{
"mcpServers": {
"matwingsvenus": {
"url": "https://YOUR_PLATFORM/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Credentials and scope
Each request uses its own credential. Every key belongs to one account. The remote tool allowlist excludes key management, passwords, payments and operations.
Transport Remote MCP over HTTPS Credential Account API key per request Endpoint /mcp Account Shared files, jobs, balance and quotas
Discover tools and prices
Use the server's discovery and quote tools before a paid call. Read the published input and result contracts; the agent does not choose executors or runtime commands.
list_tools get_tool create_quote get_balance list_files
Submit a paid job
Send mcp_submit_job with a stable submission_key. Keep the original arguments for retries. Omit the optional authorization amount to use the account default.
Use the complete, fixed-version mcp_submit_job arguments in the worked example below, including the READY-file variant. Credentials belong in transport headers, never in tool arguments.
Follow and read the result
Use the accepted job ID for status, structured results and output download requests. Read private results explicitly. MCP file inputs reference your own READY file IDs.
list_jobs get_job get_job_result get_job_output_download
Retry and cancel safely
After an uncertain response, retry the same submission_key and arguments to recover the original job. Use cancel_job to request stopping. Do not submit a replacement while the original outcome is unknown.
mcp_submit_job Reuse original submission_key and arguments cancel_job Request cancellation of the accepted job get_job Wait for confirmed outcome
Limits and privacy
An agent cannot raise the accepted authorization cap or access another account's resources. Inputs and results stay private and are not used for training. Expired content returns 410; a valid empty result has a different meaning.
Account statistics use the REST Usage and Consumption reports described in /developers/api#usage. Creation-period charges differ from settlement-period consumption; current balance and activity are separate snapshots. Null, zero and unverified usage remain distinct. MCP get_usage keeps its original arguments and response fields; new REST reporting routes are not MCP tools.
Allowed Published compute tools and owned resources Not exposed Keys, passwords, payment writes, operations Paid retries Same stable submission_key
Worked example: protein properties
protein_properties_physicochemical@2026-10-14-candidate
Checking whether this example version is currently published…
Purpose and input rules
Calculate physicochemical features from one protein sequence: length, molecular weight, theoretical pI and amino-acid composition, returned as JSON.
This version returns physicochemical features only. It does not generate a protein structure or output files. The public example is teaching material, not a new computation or a quality assessment.
- Provide exactly one of sequence or fasta_file; omit the other or set it to null. Both or neither are rejected.
- sequence must be nonempty and use only uppercase ACDEFGHIKLMNPQRSTVWY. FASTA must contain one nonempty sequence using the same alphabet; multiple records are rejected.
- task_name is fixed to Physical and chemical properties. Omit it to use the default, or send that exact constant; other tasks are not supported.
- Use a READY file owned by your account for fasta_file. Accepted formats are fasta, fa and faa. A local path is not a file_id.
- The tool input limit is 134217728 bytes. A direct JSON job request, including its metadata, is limited to 131072 bytes (128 KiB). Use a file upload and a READY reference for larger sequences. Structured results are limited to 65536 bytes.
Version 2026-10-14-candidate. Save the complete public payload below as request.json.
Set MATVENUS_API_URL to your HTTPS platform base URL and keep MATVENUS_API_KEY in a protected environment (or use your existing CLI login). Set SUBMISSION_KEY to a new unique key for this logical job; retain the same key and identical request for retries. A new job needs a new key.
{
"tool_id": "protein_properties_physicochemical",
"tool_version": "2026-10-14-candidate",
"parameters": {
"sequence": "ACDEFGHIKLMNPQRSTVWY"
}
}Remote MCP
Connect your MCP client to the platform HTTPS /mcp endpoint with Authorization: Bearer and your API key on every request. Call mcp_submit_job with the arguments below; they are client tool arguments, not an HTTP request body. Replace the submission-key placeholder with your retained key.
{
"tool_id": "protein_properties_physicochemical",
"tool_version": "2026-10-14-candidate",
"parameters": {
"sequence": "ACDEFGHIKLMNPQRSTVWY"
},
"submission_key": "REPLACE_WITH_THIS_LOGICAL_JOB_KEY"
}Set job_id to the id returned by the submit call. Call get_job until SUCCEEDED, then call get_job_result. The following blocks show tool names and arguments for your MCP client.
{
"job_id": "RETURNED_JOB_UUID"
}{
"job_id": "RETURNED_JOB_UUID"
}HTTP 202 means accepted. Keep its Job ID even after a client timeout. Result reads return 409 while not ready and 410 after deletion or expiry. Failed or cancelled jobs may have no result. A conflicting retry returns 409; inspect the original Job instead of submitting a new one.
Use a FASTA file instead
Save this public single-record sample as public-sample.fasta. Upload it through REST or CLI; MCP cannot upload binary files. Confirm the returned file belongs to your account and is READY.
The expected JSON shown here illustrates direct sequence input, whose sequence_id is temp_sequence. For FASTA input, sequence_id comes from the record header; this public FASTA uses public-sample. The sequence identifier is separate from the platform Job ID.
>public-sample ACDEFGHIKLMNPQRSTVWY
Run the upload command first, then set FILE_ID to the returned id and check that the file is 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"
Replace the file-ID placeholder with that READY UUID, then save this as request.json and submit with the REST or CLI steps above. Use a new submission key for this different logical job. sequence is omitted.
{
"tool_id": "protein_properties_physicochemical",
"tool_version": "2026-10-14-candidate",
"parameters": {
"fasta_file": {
"file_id": "REPLACE_WITH_READY_FILE_UUID"
}
}
}For MCP, use this complete mcp_submit_job argument object instead:
{
"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"
}Public sample sources
Versioned repository materials; these samples do not establish current tool availability. The enabled catalog is authoritative.
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
Understand the JSON result
Complete expected output for the public sequence. This is a stored public sample, not a computation performed by this page. There are no output files.
{
"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
}| Name | Type | Required | Notes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
success | true | Yes | A valid delivered result has success=true and nonempty data. An empty object is not a valid result for this tool. · fixed true | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data | object | Yes | no additional properties | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.sequence_id | string | Yes | Sequence identifier in the result; distinct from the platform Job ID. · min length 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.sequence_length | integer | Yes | Sequence length in amino-acid residues. · min 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.molecular_weight | number | Yes | Molecular weight. The schema does not declare a unit; maintainer clarification is pending. · greater than 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.theoretical_pI | number | Yes | Theoretical isoelectric point (pI), range 0–14. · 0–14 inclusive | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.aromaticity | number | Yes | Aromaticity value, range 0–1. Values are shown as raw fractions, not percentages. · 0–1 inclusive | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.instability_index | number | Yes | Reported instability index; no stability rating is inferred. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.gravy | number | Yes | Reported GRAVY hydropathy index; no quality rating is inferred. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.secondary_structure_fraction · 3 fields · RequiredHelix, turn and sheet fractions, each 0–1. They need not sum to 1 and do not represent a generated structure. · no additional properties
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.amino_acid_composition · 20 fields · RequiredTwenty amino-acid fractions, each 0–1. All twenty letter keys are required; 0.05 means a fraction of 5%. · no additional properties
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||