Remote MCP guide

Setup, submission and private results for MatwingsVenus Open Platform.

Remote MCP manual

Connect an MCP client to the remote server. This guide covers client configuration, exposed tools and paid-call retry rules.

01

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.

mcp-connectCopy mcp-connect example
{
  "mcpServers": {
    "matwingsvenus": {
      "url": "https://YOUR_PLATFORM/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
02

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.

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

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.

mcp-discoverCopy mcp-discover example
list_tools
get_tool
create_quote
get_balance
list_files
04

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.

05

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.

mcp-resultsCopy mcp-results example
list_jobs
get_job
get_job_result
get_job_output_download
06

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-retryCopy mcp-retry example
mcp_submit_job   Reuse original submission_key and arguments
cancel_job       Request cancellation of the accepted job
get_job          Wait for confirmed outcome
07

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.

mcp-limitsCopy mcp-limits example
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.

request.jsonCopy Public sequence request
{
  "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.

mcp_submit_job · argumentsCopy MCP submission arguments
{
  "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.

get_job · argumentsCopy MCP status arguments
{
  "job_id": "RETURNED_JOB_UUID"
}
get_job_result · argumentsCopy MCP result arguments
{
  "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.fastaCopy Public FASTA sample
>public-sample
ACDEFGHIKLMNPQRSTVWY

Run the upload command first, then set FILE_ID to the returned id and check that the file is READY.

REST · upload and check READYCopy REST file upload
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 READYCopy CLI file upload
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.

request.json · READY file variantCopy READY file request
{
  "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:

mcp_submit_job · READY file argumentsCopy MCP READY file arguments
{
  "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: 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

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.

expected-sequence-result.jsonCopy Public expected result
{
  "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
}
NameTypeRequiredNotes
successtrueYesA valid delivered result has success=true and nonempty data. An empty object is not a valid result for this tool. · fixed true
dataobjectYesno additional properties
data.sequence_idstringYesSequence identifier in the result; distinct from the platform Job ID. · min length 1
data.sequence_lengthintegerYesSequence length in amino-acid residues. · min 1
data.molecular_weightnumberYesMolecular weight. The schema does not declare a unit; maintainer clarification is pending. · greater than 0
data.theoretical_pInumberYesTheoretical isoelectric point (pI), range 0–14. · 0–14 inclusive
data.aromaticitynumberYesAromaticity value, range 0–1. Values are shown as raw fractions, not percentages. · 0–1 inclusive
data.instability_indexnumberYesReported instability index; no stability rating is inferred.
data.gravynumberYesReported GRAVY hydropathy index; no quality rating is inferred.
data.secondary_structure_fraction · 3 fields · Required

Helix, turn and sheet fractions, each 0–1. They need not sum to 1 and do not represent a generated structure. · no additional properties

NameTypeRequiredNotes
data.secondary_structure_fraction.helixnumberYes0–1 inclusive
data.secondary_structure_fraction.turnnumberYes0–1 inclusive
data.secondary_structure_fraction.sheetnumberYes0–1 inclusive
data.amino_acid_composition · 20 fields · Required

Twenty amino-acid fractions, each 0–1. All twenty letter keys are required; 0.05 means a fraction of 5%. · no additional properties

NameTypeRequiredNotes
data.amino_acid_composition.AnumberYes0–1 inclusive
data.amino_acid_composition.CnumberYes0–1 inclusive
data.amino_acid_composition.DnumberYes0–1 inclusive
data.amino_acid_composition.EnumberYes0–1 inclusive
data.amino_acid_composition.FnumberYes0–1 inclusive
data.amino_acid_composition.GnumberYes0–1 inclusive
data.amino_acid_composition.HnumberYes0–1 inclusive
data.amino_acid_composition.InumberYes0–1 inclusive
data.amino_acid_composition.KnumberYes0–1 inclusive
data.amino_acid_composition.LnumberYes0–1 inclusive
data.amino_acid_composition.MnumberYes0–1 inclusive
data.amino_acid_composition.NnumberYes0–1 inclusive
data.amino_acid_composition.PnumberYes0–1 inclusive
data.amino_acid_composition.QnumberYes0–1 inclusive
data.amino_acid_composition.RnumberYes0–1 inclusive
data.amino_acid_composition.SnumberYes0–1 inclusive
data.amino_acid_composition.TnumberYes0–1 inclusive
data.amino_acid_composition.VnumberYes0–1 inclusive
data.amino_acid_composition.WnumberYes0–1 inclusive
data.amino_acid_composition.YnumberYes0–1 inclusive