Immuno Graph MCP Server

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<br/>46 typed tools"]
    S --> D["Local calculations<br/>and exact fixtures"]
    S --> L["Optional live<br/>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<br/>PDBQT"]
    L["Compound / SMILES"] --> M["RDKit + Meeko ligand<br/>SDF + PDBQT"]
    R --> V["AutoDock Vina"]
    M --> V
    V --> POSE["Pose PDBQT<br/>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 bonds.

The live docking guide documents inputs, runtime requirements, example files, and verification of the exported pose chain. An interactive 3D viewer visualizes returned coordinate data; neither image establishes experimental binding.

Provenance you can inspect

The 46-tool reality matrix records what each tool actually computes or fetches and the verification performed. In particular, GraphBepi is fixture-only in this release; Parker is a hydrophilicity calculation; BepiPred-3.0 is the supported live B-cell option when enabled.

Tool catalog

See the complete tool catalog and input contracts. To try one call, invoke validate_sequence with:

{
  "fasta": ">protein\nACDEFGHIK",
  "profileVersion": "mvp-v1.0"
}

It returns the normalized sequence, length, and SHA-256 identity, or a structured validation error.

Enable live connectors

Most live connectors are disabled by default. Set flags in the MCP server's environment and install the relevant provider runtime or allow its network endpoint. .env.example lists the settings.

If a required provider or binary is unavailable, the tool returns an explicit failure or a labelled fallback according to the requested policy. The npm tarball and container do not bundle optional scientific binaries or model downloads.

HTTP deployment

npm run start:http serves http://127.0.0.1:3000/mcp locally, with GET /health as a health probe. For a remote endpoint, set HOST=0.0.0.0, a long IMMUNOGRAPH_API_KEY, exact IMMUNOGRAPH_ALLOWED_HOSTS and IMMUNOGRAPH_ALLOWED_ORIGINS, and terminate TLS at your ingress. The image runs the HTTP entry point by default; publishing the image does not create a managed endpoint. Read SECURITY.md before deployment.

Verification and scope

The CI workflow checks Windows and Linux on Node.js 20 and 22. A standard MCP client has exercised all 46 documented examples; the semantic audit checks calculations, provenance, and artifact hashes. The v0.2.1 container release run tested 46-tool discovery and a real call over Docker stdio, guarded HTTP, and a test TLS ingress. The protocol audit also checks that every tool advertises parameter descriptions and a structured result schema. These checks establish software behavior and packaging, not the accuracy of every scientific method or continuous availability of third-party services.

The motivation is familiar in epitope research: studies such as Grifoni et al. (2020) and Ferreira et al. (2021) combine sequence analysis, prediction, conservation, and other evidence across tools. ImmunoGraph makes computational handoffs easier to inspect; independent review and experimental validation remain necessary.

Contribute and get help

Contributions and reproducible bug reports are welcome. Start with CONTRIBUTING.md, open an issue, and report security concerns through SECURITY.md. Released changes are in CHANGELOG.md. ImmunoGraph is available under the MIT license.