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.immport.org/auth/api/keys

Available Tools

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

Tool	Auth	Description
`search_studies`	Public	Full-text and faceted search across all ImmPort studies
`search_subjects`	Public	Search and filter subjects across studies by demographics and clinical attributes
`get_study_data`	Required	Retrieve any of 22 sub-resources for a single study: summary, arm, planned visits, experiments, protocols, personnel, publications, adverse events, biosample, lab tests, and more
`get_study_data_availability`	Required	Returns a record-count inventory for every data category in a study — call this first to confirm which data types exist before querying
`get_assay_results`	Required	Numeric assay results for 11 assay types (ELISA, HAI, ELISPOT, flow cytometry, HLA typing, KIR typing, mass spectrometry, MBAA, neutralization titres, PCR, file paths) across one or more studies
`lookup_controlled_vocabulary`	Public	All 45 ImmPort controlled vocabulary tables served from an in-memory cache
`get_study_files`	Required	Study file manifest, inline streaming for text files, and signed download URLs for zip archives

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

Go to Customize → Connectors and click +
Select Add Custom Connector
Enter a name (e.g. ImmPort), set URL to https://mcp.immport.org
Set Client ID to immport-mcp-client and leave Client Secret blank
Click Connect — you will be redirected to the ImmPort login screen
Sign in with your ImmPort production credentials
After login, claude.ai receives an access token. It is forwarded automatically on every tool call — no further configuration is needed

Connecting ImmPort MCP Server in claude.ai

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

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

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

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.immport.org/auth/api/keys. If you connected via OAuth2 (claude.ai), the server handles token refresh automatically.

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