ImmunoGraph MCP

ImmunoGraph MCP

A standard Model Context Protocol server for computational epitope research. Call 46 typed tools for sequence processing, immune evidence, structure and chemistry analysis, docking, and reviewable exports. Results carry provenance so a live provider result stays distinct from a fixture or synthetic demonstration.

Problem · Who it is for · User flow · Get started · 3D outcomes · All 46 tools · Contribute

[!IMPORTANT]

ImmunoGraph supports computational research, not clinical or experimental validation. A predicted epitope, docking pose, score, or exported 3D model does not establish binding, vaccine efficacy, or safety. Fixture and synthetic results are demonstrations and are labelled as such.

The problem

An epitope research workflow crosses different kinds of software: sequence processing, immune predictors, HLA coverage, structure databases, molecular preparation, docking, interaction analysis, and reporting. Each step has its own input format, runtime, and scientific assumptions. When an LLM or research application chains them together, it must also keep track of *which inputs and methods produced each result*. A plausible looking score or 3D view is easy to misread if its source is missing.

ImmunoGraph gives an MCP host one typed interface for these steps. The host can discover and call individual tools, pass outputs between them, and inspect explicit source labels and exported bytes. This reduces custom integration code for a reviewable computational workflow; it does not replace scientific judgment or validate a prediction by itself.

Who it is for

The outputs are for research and education. Clinical decisions, efficacy claims, and experimental validation require independent methods and evidence.

What you can do

This is one server with 46 tools, not 46 independent live data providers. Each tool is callable on its own. A client passes results between calls when building a workflow.

User flow

The researcher works in an MCP-enabled chat or application. The client chooses the calls and carries evidence forward; ImmunoGraph executes each requested operation and returns a typed result.

This flow is modular: a user can call one tool without running every stage. run_agentic_workflow executes caller-supplied, approved tool calls; without those calls it returns a plan rather than silently launching a full study. See architecture and the tool reality matrix for exact execution boundaries.

Get started

Install the public release

Node.js 20 or newer is required. The versioned tarball is hosted on GitHub and installs with npm; the immunograph-mcp name is not yet published on the npm registry.

npm install --global https://github.com/Ajey95/immuno-graph/releases/download/v0.2.1/immunograph-mcp-0.2.1.tgz

Register the installed command in an MCP host that supports stdio servers:

{

"mcpServers": { "immunograph": { "command": "immunograph-mcp" } } }

The server speaks MCP on stdio, so launch it through your host. If the host cannot find the globally installed command, configure its absolute path. The GitHub release also includes the source and a SHA-256 checksum for the tarball. The downloaded public tarball matched that checksum.

Run the public container

The official MCP Registry entry points to the public OCI image. For a local stdio host, use:

{

"mcpServers": { "immunograph": { "command": "docker", "args": [ "run", "--rm", "-i", "ghcr.io/ajey95/immuno-graph:0.2.1", "node", "dist/index.js" ] } } }

The container also supports guarded Streamable HTTP at /mcp. See HTTP deployment for its required security settings.

Build from source

git clone https://github.com/Ajey95/immuno-graph.git

cd immuno-graph npm ci npm run check npm start

npm start serves stdio MCP. npm run check runs the software tests, build, all-tool example calls, semantic audit, dependency audit, and package dry run. For a host, point command at node and args at the absolute path to dist/index.js.

How it works

flowchart LR

A["FASTA · PDB · SMILES"] --> H["MCP host"] H --> S["ImmunoGraph 46 typed tools"] S --> D["Local calculations and exact fixtures"] S --> L["Optional live connectors"] D --> R["Results + provenance"] L --> R R --> O["Reports · 3D files · ZIP"]

The host chooses which tools to call. ImmunoGraph validates typed inputs, executes a handler, and returns structured success or failure data with run metadata and source labels. The server does not silently run a full study or treat fixture values as live evidence. See architecture for transport and module details.

Technical design

The registry entry points to the published OCI image. Optional scientific binaries, model downloads, and third-party service availability remain separate runtime requirements.

A research workflow

flowchart LR

FASTA["Protein FASTA"] --> V["Peptide windows"] V --> E["Immune evidence"] E --> R["Constraints + ranking"] R --> X["Reviewable exports"] E -.->|Optional| S["Structure + docking"] S -.-> X

These are separate MCP calls. Rankings and reports depend on the evidence the client supplies. With live prediction disabled, an arbitrary new protein has no automatic scientific binding result.

Docking and 3D files

Configured live tools can use actual coordinates rather than decorative models:

flowchart LR

P["Protein PDB"] --> R["Meeko receptor PDBQT"] L["Compound / SMILES"] --> M["RDKit + Meeko ligand SDF + PDBQT"] R --> V["AutoDock Vina"] M --> V V --> POSE["Pose PDBQT complex PDB"] POSE --> VIEW["3D viewer HTML"] POSE --> PLIP["PLIP contacts"] POSE --> ZIP["Research ZIP"]

Real 3D outcomes

1IEP + imatinib: exported top Vina pose. This figure is rendered from a saved complex PDB produced by a LIVE_ONLY MCP docking call. Panel A traces the protein Cα coordinates and shows the ligand; panel B shows the ligand and protein atoms within 5 Å. The render script reproduces the image from those coordinates. This is a docking capability example, not an epitope candidate; the pose score is a computational estimate, not measured affinity.

1UYD + PubChem CID 2244: three computed poses. This figure comes from the live docking research ZIP, which includes the receptor, ligand, Vina poses, complex, and image. Its run provenance and summary identify the sources and nine generated poses; the image shows three of them. The callouts show distances calculated from the coordinates; dashed polar contacts are inferred geometry, not experimentally established bo