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

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

---

Available Tools

The server exposes 7 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 22 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_study_data_availability — requires auth

Returns a record-count inventory for every ImmPort data category in a study — how many rows have been parsed into the database. Call this before get_study_data or get_assay_results to confirm which data types actually exist for a study and avoid wasted API calls.

get_study_data_availability("SDY1")
# Returns counts per category, e.g.:
# { "hai_result": 240, "elisa_result": 0, "assessment_component": 98893, ... }

• A count of 0 means the data has not been parsed into the database — it may still exist in the study files.
• A very large count (e.g. assessment_component > 10000) signals that using the Tab.zip download is more efficient than multiple API calls.

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 45 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

The ImmPort MCP Server supports two authentication methods. Choose the one that matches your client:

Method	How it works	Use when
OAuth2 login	Your AI assistant redirects you to the ImmPort login page. After sign-in, an access token is issued and forwarded automatically on every request. No API key is needed.	Web-based AI assistants (claude.ai, ChatGPT, Gemini) that support OAuth2 connectors
API key (Bearer token)	Obtain a 30-day ImmPort API key from the portal and supply it as an Authorization: Bearer <key> header in your client's configuration.	Desktop apps, CLI tools, scripts, and IDE extensions (Claude Desktop, Claude Code, Google Antigravity)

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

---

OAuth2 — Web-based AI Assistants

Web-based AI platforms that support OAuth2 MCP connectors handle the full login flow inside the browser. You sign in once with your ImmPort credentials and the platform stores and refreshes the access token automatically — no API key to manage or rotate.

claude.ai

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. After login, claude.ai receives an access token. It is forwarded automatically on every tool call — no further configuration is needed

---

API Key (Bearer Token) — Desktop, CLI, and IDE Agents

For clients that are not browser-based, authenticate by passing your ImmPort API key as a Bearer token in the Authorization header. The server accepts the key directly — there is no OAuth2 redirect involved.

Before you begin: download your API key from https://www.dev.immport.org/auth/api/keys. Open the downloaded JSON file and copy the value of the "api_key" field. Keys are valid for 30 days — see the note at the bottom of this page about renewal.

Claude Desktop

Add the following block to your Claude Desktop configuration file:

• Linux / macOS: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Replace <your_immport_api_key> with the value from your downloaded key JSON, then restart Claude Desktop.

---

Claude Code

Register the server once from the terminal. Claude Code stores the configuration persistently across sessions.

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

Verify the connection:

claude mcp list
# Expected output:
# immport: https://mcp.immport.org - Connected

To update the key after renewal, remove and re-add the server:

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

---

Google Antigravity IDE

Antigravity uses a raw JSON config file to register MCP servers.

1. Press ++ctrl+alt+b++ (Windows/Linux) or ++cmd+option+b++ (macOS) to open the Agent Panel
2. Click the ⋮ menu at the top-right and select MCP Servers
3. Click Manage MCP Servers → View raw config — this opens mcp_config.json in the editor
4. Add the following inside the mcpServers object:

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

1. Save the file (++ctrl+s++ / ++cmd+s++) and click Refresh in the MCP Servers pane

Note

Antigravity uses serverUrl (not url) as the key for remote MCP servers.

---

Tips for Best Results

Check data availability first

Before fetching study data or assay results, call get_study_data_availability for the study. It returns record counts for every data category in one fast call — so you know exactly which assay types and resources are worth querying before making any additional requests.

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.

---

Related Pages

• API Keys — how to create and manage ImmPort API keys
• ImmPort Authentication Service — OAuth2 overview
• Shared Data API — direct REST API access