Skip to content

ImmPort MCP Server

Beta — Not Production Stable

The ImmPort MCP Server is currently in beta. Functionality, tool interfaces, and authentication flows may change without notice. It is not recommended for production workflows or critical research automation at this time. Please share feedback and bug reports with the ImmPort help desk at ImmPort_Helpdesk@immport.org.

The ImmPort Model Context Protocol (MCP) Server gives AI assistants — such as Claude, ChatGPT, and Gemini — direct, structured access to ImmPort's immunology research data through natural language.

Live endpoint: https://mcp.immport.org

What You Can Do

Once connected, ask your AI assistant questions like:

  • "Find influenza vaccine studies with flow cytometry data and more than 50 subjects"
  • "Compare HAI antibody responses across SDY306 and SDY208 — show pre/post-vaccination titres"
  • "What demographics were enrolled in SDY1? Are there protocol documents I can read?"
  • "Give me a signed download link for the Tab.zip release package for SDY3510"

Authentication

The MCP server supports two authentication modes:

Mode How it works Best for
OAuth2 login Sign in with your ImmPort account via your AI assistant's OAuth2 connector. The access token is forwarded automatically. claude.ai, ChatGPT, other browser-based AI assistants
API key Obtain a 30-day ImmPort API key and pass it as a Bearer token in the Authorization header. Claude Desktop, Claude Code, curl, scripts

To obtain an API key: https://www.dev.immport.org/auth/api/keys

Available Tools

The server exposes 6 composable tools covering the full ImmPort data surface:

search_studies — public, no auth required

Full-text and faceted search across all ImmPort studies.

search_studies(term="influenza", page_size=10)
search_studies(term="COVID-19", source_fields=["study_accession","brief_title","actual_enrollment"])

search_subjects — public, no auth required

Search and filter subjects across studies by demographics and clinical attributes.

search_subjects(species=["Homo sapiens"], sex=["Female"], page_size=50)

get_study_data — requires auth

Retrieve any of 24 sub-resources for a single study: summary, subjects, arm, planned visits, experiments, protocols, personnel, publications, adverse events, immune exposure, biosample, lab tests, and more.

get_study_data("SDY1", resource="summary")
get_study_data("SDY1", resource="subjects")
get_study_data("SDY1", resource="experiments")

get_assay_results — requires auth

Numeric assay results for 11 assay types across one or more studies, with rich filters (time point, sex, biosample type, etc.).

Assay type Description
elisa ELISA antibody measurements
hai Hemagglutination inhibition titres
elispot ELISPOT cell counts
fcs_analyzed Flow cytometry analyzed results
hla_typing HLA typing results
kir_typing KIR typing results
mass_spectrometry Mass spectrometry results
mbaa Multiplex bead array assay
neut_ab_titer Neutralization antibody titres
pcr PCR results
file_paths Paths to raw result files 
get_assay_results(assay_type="hai", study_accession=["SDY306","SDY208"])
get_assay_results(assay_type="fcs_analyzed", study_accession=["SDY3510"], sex=["Female"])

lookup_controlled_vocabulary — public, no auth required

All 44 ImmPort controlled vocabulary tables served from an in-memory cache. Zero latency.

lookup_controlled_vocabulary("lkDisease")
lookup_controlled_vocabulary("lkSex")
lookup_controlled_vocabulary("lkVirusStrain")

get_study_files — requires auth

Study file manifest, inline streaming for text files, and signed download URLs for zip archives.

get_study_files(action="manifest", study_accession="SDY1")
get_study_files(action="download", file_uuid="97a310f6-...")   # returns signed URL
get_study_files(action="stream",   file_uuid="325b0667-...")   # inline TSV content

Connecting Your AI Assistant

claude.ai

claude.ai connects via OAuth2 — you log in with your ImmPort credentials directly inside the claude.ai interface. No API key is needed.

  1. Go to Customize → Connectors and click +
  2. Select Add Custom Connector
  3. Enter a name (e.g. ImmPort), set URL to https://mcp.immport.org
  4. Set Client ID to immport-mcp-client and leave Client Secret blank
  5. Click Connect — you will be redirected to the ImmPort login screen
  6. Sign in with your ImmPort production credentials
  7. The access token is forwarded automatically on every tool call

Connecting ImmPort MCP Server in claude.ai

Claude Desktop

Add the following to your Claude Desktop configuration file (~/.config/Claude/claude_desktop_config.json on Linux/macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "immport": {
      "url": "https://mcp.immport.org",
      "headers": {
        "Authorization": "Bearer <your_immport_api_key>"
      }
    }
  }
}

Replace <your_immport_api_key> with the api_key value from your downloaded key JSON. Restart Claude Desktop after saving.

Claude Code

Remote server (recommended):

claude mcp add --transport http immport https://mcp.immport.org \
  --header "Authorization: Bearer <your_immport_api_key>"

claude mcp list   # verify: immport - Connected

Local development

Local installation instructions are coming soon. Stay tuned.

HTTP / curl

You can call the MCP server directly with curl for testing:

curl -s -X POST https://mcp.immport.org \
  -H "Authorization: Bearer <your_immport_api_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Tips for Best Results

Use parallel tool calls

Many AI assistants support calling multiple tools at once. Ask for several study resources in a single message — e.g. "Give me the summary, subjects, and experiments for SDY1" — and the assistant will fetch all three in parallel.

Tab.zip for deep analysis

For comprehensive single-study analysis, ask for the Tab.zip download link instead of multiple get_study_data calls. The zip contains every study metadata table as a TSV file. "Get me a download link for all structured data from SDY3510"

Public tools need no login

search_studies, search_subjects, and lookup_controlled_vocabulary are public — they work without any API key. Connect these first to explore available data before authenticating.

API key expiry

ImmPort API keys expire after 30 days. Renew at https://www.dev.immport.org/auth/api/keys. If you connected via OAuth2 (claude.ai), the server handles token refresh automatically.