MoleculemindOS MCP (@moleculemind/mos-mcp)

Customer-facing MCP server for MOS gateway project, object, and task v2 APIs.

Requirements

• Node.js 20+
• A MOS API key (mos-sk-…) with access to projects, objects, tasks, and GET /v1/uni_model_configs/model_runtime_configs

Configuration

| Env | Required | Description | |-----|----------|-------------| | MOS_BASE_URL | no | Gateway base URL, default is https://mos.moleculemind.com | | MOS_API_KEY | yes | Bearer API key (mos-sk-…) |

Cursor / Claude Desktop

{
  "mcpServers": {
    "mos": {
      "command": "npx",
      "args": ["-y", "@moleculemind/mos-mcp@latest"],
      "env": {
        "MOS_API_KEY": "mos-sk-..."
      }
    }
  }
}

Local checkout:

{
  "mcpServers": {
    "mos": {
      "command": "node",
      "args": ["/absolute/path/to/mos_gateway/mcp/dist/index.js"],
      "env": {
        "MOS_BASE_URL": "https://api.example.com", // optional
        "MOS_API_KEY": "mos-sk-..."
      }
    }
  }
}

Tools (v1)

Projects: list_projects, get_project, create_project
Objects: list_objects, get_objects_metadata, download_object_content, upload_object
Tasks: list_tasks, get_task
Quota: get_mos_quota (task-creation limit/used/remaining/reset_time; check before batch create_*)
Create (display-named):

download_object_content writes bytes directly to its required absolute output_path. Agents should use <workspace>/<task>/result/<filename> when that context exists. Parent directories are created automatically; existing files are preserved unless overwrite: true is explicitly supplied.

| Tool | type | |------|--------| | create_structure_prediction_task | mos-mmfold | | create_protein_binder_design_task | mos-wf-rfdiffusion | | create_sequence_homology_search_task | mos-blast | | create_sequence_fitness_mutation_effect_task | mos-score-esm | | create_evolutionary_mutation_effect_task | mos-score-msat | | create_structural_stability_mutation_effect_task | mos-score-ligandmpnn | | create_binding_affinity_mutation_effect_task | mos-diffaffinity | | create_antibody_humanization_task | mos-wf-humanization |

No delete/cancel tools in v1. workId is omitted on create.

Layout

mcp/src/
  index.ts                 # stdio entry
  config.ts                # env + package identity
  create-server.ts         # wires tool modules onto McpServer
  catalog/                 # create-task tool catalog (mos-* mapping)
  gateway/                 # HTTP client + runtime schema cache
  models/                  # per-model payload builders (e.g. MMFold)
  tools/                   # MCP tool registrations by domain
  lib/                     # small shared utilities (Ajv)

Agent instructions

The MCP server advertises compact instructions (resource model, async/no-poll, metadata vs download). Tool descriptions use a short what + When: pattern; shared rules live in instructions to save tokens.

Async model jobs

Create-task tools return a taskId immediately. Jobs may run for many minutes. Do not poll get_task in a loop — call it later when the user asks (or after a long gap). There is no wait_for_task tool in v1.