Why Claude for this workshop? ImmPort isn't endorsing or promoting Claude over other AI tools. We picked it for this session because it's easy to demo from a browser and has a free account tier — no install required. The ImmPort MCP Server itself is a standard MCP server and works with any MCP-compatible client (see the Appendix).
⏱ Session Timeline (10:25 AM PT / 1:25 PM ET)
Account & Setup1:25 – 1:35 ET · 10 min
Connect to MCP1:35 – 1:45 ET · 10 min
Data Discovery Exercise1:45 – 2:10 ET · 25 min
Q&A2:10 – 2:25 ET · 15 min
We'll move through each section together — the facilitator will let you know when to proceed.
What is an MCP Server?
MCP (Model Context Protocol) is an open standard by Anthropic that lets AI assistants connect to external data systems through a consistent interface.
An MCP Server wraps an existing data source — like ImmPort's REST APIs — and exposes them as tools the AI can call automatically.
A tool is simply a named function with a description the AI reads to know when and how to use it. When you ask Claude a question, it picks the right tools, fills in the parameters, calls them, and synthesizes the results into a plain-English response.
🧠
You + AI Client
Ask a question in plain English
→
⚙️
ImmPort MCP Server
Translates to API calls & returns structured data
→
🗄️
ImmPort Database
Same data as Swagger API — no difference
💡
REST API vs MCP: Both access the same ImmPort data. With the Swagger API you write code — construct the request, parse the JSON, interpret the result. With MCP, you just ask: "Find RA studies with female subjects" and Claude calls search_studies(condition_or_disease="Rheumatoid Arthritis", sex="Female") for you, handles pagination, and summarizes the output.
Why MCP instead of just pointing the AI at the API docs?
"An API that is sophisticated for a human is one with rich, composable, atomic parts. An API that is sophisticated for an agent is one that is ruthlessly curated and minimalist."
— Jeremiah Lowin, FastMCP author, "Stop Converting Your REST APIs to MCP" (2025)
🌐 Raw REST API / Swagger docs alone
86 endpoints — AI spends context window just choosing the right one
Response-only fields silently ignored as query filters — wrong results, no error
No guidance when a study's data lives in files rather than the database
44 vocabulary tables need a separate lookup call before every query
No cross-endpoint workflow guidance (e.g. file manifest → download)
✅ ImmPort MCP Server (curated)
7 composable tools — fewer choices, less noise, easier to chain
Only valid query filters exposed — phantom parameters removed
Every answer grounded in a real API call — the AI can't invent data
Sparse-data guidance built into tool descriptions
All 44 vocabulary tables pre-loaded at startup — zero query-time cost
Available Tools
Tool
What it does
Example use
search_studies
Full-text and faceted search across all ImmPort studies. Filters by disease, assay type, sex, age, species, program, and more.
"Find RA studies with female subjects"
search_subjects
Search for subjects across studies with demographic and phenotype filters.
"How many pediatric subjects in HIPC studies?"
get_study_data
Fetch any sub-resource for a study — arms, subjects, biosamples, experiments, lab tests, protocols, and more.
"Show me the subject demographics for SDY998"
get_study_data_availability
Get a record-count inventory of every data category in a study — useful for quickly assessing what data is available before fetching.
"What kinds of data does SDY998 have?"
get_study_files
List, stream, or download study files — protocol documents, result files, data release packages.
"List the protocol documents for SDY998"
get_assay_results
Query assay result data across 20+ assay types — flow cytometry, ELISA, HAI titers, RNA-seq, PCR, HLA typing, mass spectrometry, and more.
"Get the HAI titer results for SDY998"
lookup_controlled_vocabulary
Retrieve valid values for any ImmPort lookup table — diseases, assay types, species, demographics, and more. Served from in-memory cache.
"What assay types are available in ImmPort?"
🔑 Part 1 — Account Setup
1:25 – 1:35 ET10 min
⏰ Target: 1:35 ET. We'll aim to move to connecting Claude around 1:35.
🔐
Complete before the workshop if possible. You have two account setup paths for ImmPort: Native registration (username/password + email activation + MFA) or Sign in with Gmail. Choose whichever is faster for you.
🔑 Path A — Native ImmPort Registration
Standard path
Use this path if you prefer creating a standard ImmPort account with username/password, email activation, and MFA setup.
1
Open the ImmPort registration page (screenshots registration/2–3)
Complete MFA setup with Email OTP (screenshots registration/8–11)
Select Email OTP when prompted
Check your email for the OTP code
Enter the OTP to finish setup
🔐
MFA is required on every login. ImmPort sends a one-time code to your registered email address — have your email open during the workshop. OTP emails typically arrive within 30–60 seconds; allow up to 2 minutes before retrying.
🛑
Common issues: OTP not arriving? Check your spam/junk folder. Code expired? Request a new one — OTP codes are valid for ~5 minutes only. See Troubleshooting for more.
📸 ImmPort Registration — step by step
🔐 Path B — Register with Sign in with GmailFast path
You can also create your ImmPort account using Sign in with Gmail. This is often the quickest path during the workshop.
After sign-in, you'll still complete your profile and can set up MFA based on your account state.
1
Open ImmPort login and choose Gmail (screenshots gmail/1–2)
Close Customize. Click "New Chat" — you're ready to start the exercise.
The ImmPort connector must be enabled per chat — if the tools don't appear, check the connector toggle in the chat's sidebar.
📸 Connecting Claude to ImmPort — step by step
🔬 Part 3 — Data Discovery Exercise
1:45 – 2:10 ET25 min interactive
⏰ Target: 2:10 ET. We'll go through each prompt together as a group.
🎯
Goal: Find rheumatoid arthritis studies in ImmPort with female subjects, deep-dive into SDY998's structure and biosamples, and download a raw data file — all in plain English, no code.
🎲
Your results may not look identical to the screenshots. Claude's exact wording, formatting, and even which tools it calls can vary from run to run — that's normal for an AI agent. What shouldn't vary is the underlying data: every answer is grounded in a live ImmPort API call, not memorized or invented, so you should land on the same studies, numbers, and files even if Claude gets there by a different path.
Exercise Step A — Find RA Studies with Female Subjects (screenshots 12–13)
A1
Type this prompt into Claude:
Promptfind RA studies in ImmPort that have female subjects
✅ Expected — 13 studies
Claude calls search_studies and returns a table of 13 rheumatoid arthritis studies including SDY824, SDY998, SDY146, SDY823 and others, showing enrollment numbers and sex breakdown.
Exercise Step B — Deep Dive into SDY998 (screenshots 14–15)
B1
Ask what the study actually is and how it's structured:
PromptWhat's SDY998? How's this study actually structured — what are the different arms?
✅ Expected — screenshot 14
Claude calls get_study_data(resource="summary") and get_study_data(resource="arm") and returns a structured writeup: SDY998 — AMP Rheumatoid Arthritis Phase 1: a large, multi-institution pilot study from NIH's Accelerating Medicines Partnership (AMP RA/SLE), launched in 2016. It's a methods/technology-validation study — not a drug trial — testing whether high-dimensional profiling (RNA-seq, mass cytometry, flow cytometry, single-cell sequencing) can distinguish RA from osteoarthritis at the tissue level. Includes PI/leadership consortium, enrollment (62 subjects), sex breakdown, and tissue/data types (synovial tissue, PBMC, clinical data, histology).
B2
Pull the biosample data by arm:
PromptCan you pull the biosample data and show me what sample types came from which arm? Curious if RA and OA were sampled the same way
✅ Expected — screenshot 15
Claude calls get_study_data(resource="biosample"), then runs a few commands to aggregate the results. Returns the full biosample table (886 sample records) broken down by arm × sample type — synovial tissue, sorted fibroblasts/monocytes/T cells/B cells, whole blood, serum, PBMC — showing RA synovial biopsy was sampled far more deeply (e.g. 262 synovial tissue records) than the two arthroplasty arms.
Exercise Step C — File Inventory & Download (screenshots 16–20)
C1
Ask what files ImmPort actually has on file:
PromptWhat files does ImmPort actually have on file for this study?
✅ Expected — screenshot 16
Claude calls get_study_files(manifest, SDY998), then categorizes the results. Returns 1,016 total files: study & protocol documents (17 — 4 data-curation notes plus 13 protocol/SOP PDFs, including the full clinical protocol, lab manual, and CyTOF/CEL-Seq2 protocols), release packages (10 — Tab.zip / MySQL.zip metadata dumps, manifest/summary files), and raw result files (956 — the bulk of the study: 484 FCS flow/CyTOF files, 163 .ets + 66 .vsi whole-slide histology tiles, 105 tif/58 jpg/2 svs images, 58 PDF reports, plus sequencing outputs) — on top of an 11.7 TB bulk archive containing everything.
C2
Grab a download link for one of the histology files:
PromptGrab me a download link for one of those histology files so I can see what we're working with
✅ Expected — screenshot 17
Claude finds a histology JPEG from subject 300-0133 (RA arthroplasty arm) — a low-res "Map" thumbnail (~103 KB) of the full slide scan — and calls get_study_files(download) to generate a signed CloudFront download URL.
C3
Click the link and view the file:
Claude asks "You're leaving Claude to visit an external link" — click Open link(screenshot 18)
The JPEG downloads in your browser (screenshot 19 — "101 KB · Done")
Open it to see an H&E-stained synovial tissue section at 10x magnification (screenshot 20)
⚠️
Signed URLs expire in ~1 hour. If a link fails, ask Claude: "Give me a fresh download link."
📸 Data Discovery Exercise — screenshots 12–20
⭐ Bonus — Where MCP Truly Shines
These prompts show what makes MCP different from a keyword search or a direct API call. The terms below — women's health, non-invasive biomarkers, environmental exposure — don't appear as controlled vocabulary facets or free-text fields in ImmPort studies. The AI agent reasons across study descriptions, condition terms, assay types, and protocols to surface relevant datasets. Try them and see what it finds.
+1
Bonus promptFind women's health datasets in ImmPort.
The agent interprets a broad research theme — not a single disease term — and maps it across conditions, demographics, and study types. It also proactively reports gaps (e.g. no endometriosis studies found) rather than just listing matches. Example output:
Strongest categories
🤰 Pregnancy & preterm birth — largest cluster (163 studies matched "pregnancy"; 47 tagged to that condition), mostly under the March of Dimes program. Key studies: SDY1326 (proteomic clock of pregnancy), SDY1157 (immune response throughout pregnancy), SDY1869 (metabolome/proteome/immunome trajectories predicting labor onset), SDY2964 (chemical exposome in preterm vs. term births).
💉 Vaccine response during pregnancy — SDY37 (influenza, n=335), SDY3472 (de novo vaccination timing and newborn immunity), SDY2247 (COVID-19 mRNA vaccine, Omicron).
Notable gaps: No endometriosis studies found. Endometriosis, PCOS, and menopause are not well represented — ImmPort's women's-health content is concentrated in pregnancy/reproductive immunology rather than gynecologic conditions.
+2
Bonus promptList transplant studies with non-invasive biomarkers for detecting allograft rejection.
The agent combines a clinical context (transplant), a measurement constraint (non-invasive), and a clinical outcome (rejection) — none of which map to a single ImmPort facet. It also distinguishes study intent (biomarker discovery vs. safety monitoring) and offers to go deeper. Example output:
Top matches — non-invasive rejection monitoring
🏆 SDY557 – Noninvasive Monitoring in Kidney Transplantation (CTOT-01) — n=280 · urine, whole blood, PBL · ELISPOT, ELISA, Luminex xMAP, Q-PCR. Explicitly a noninvasive-monitoring study — best starting point.
🔬 SDY479 – Urinary cell mRNA profiles of rejection (CTOT-04) — n=494 · urine + whole blood · Q-PCR. Landmark urinary-biomarker study behind the well-known CD3ε/18S mRNA rejection signature.
🧒 SDY131 – Pediatric Kidney Transplant Without Calcineurin Inhibitors — n=34 · urine + whole blood · Q-PCR. Designed to find biomarkers that reduce reliance on biopsy in pediatric recipients.
🩸 SDY1361 – B cell sequencing in kidney transplant recipients — n=27 · whole blood/PBMC · BCR repertoire sequencing — blood-based immune-repertoire approach to rejection/tolerance signatures.
Agent follow-up offered: "This search matched 161 studies on 'allograft rejection biomarker' — there may be additional hits under other phrasing (dd-cfDNA, molecular microscope). I can re-run with those terms for a more exhaustive sweep."
+3
Bonus promptFind allergy datasets with environmental exposure data.
The agent links an immune condition with an exposure type — reasoning across study design descriptions and assay context rather than matching a controlled vocabulary term. It also contextualises the results within ImmPort's broader research programs. Example output:
Best matches
🏆 SDY1644 – Urban Environmental Factors and Childhood Asthma (URECA, ICAC-07) — n=1,218 · cord blood, nasal swabs, PBMC, plasma. Standout hit — a birth-cohort study explicitly designed to link urban environmental exposures (allergens, pollutants, microbial exposure) to childhood asthma/atopy development.
🪳 SDY223 – Cockroach Sublingual Immunotherapy Pilot (ICAC-12) — n=54 · indoor allergen exposure is central to the study design.
🏙 SDY210 – Asthma Control Evaluation (ACE, ICAC-02) — n=546 · Inner City Asthma Consortium, which specifically studies inner-city/indoor environmental allergen exposure.
Program context: Most of ImmPort's allergy data comes from the Inner City Asthma Consortium (ICAC) — 15 studies focused on urban/environmental drivers — and CoFAR (food allergy, more immune-mechanism than exposure-focused).
Notable gap: Most "environmental" hits in ImmPort skew toward radiation or chemical/pregnancy exposomics rather than classic allergen exposure (dust mite, pollen, pet dander, air pollution) paired with allergy outcomes. SDY1644 is the only large-scale study pairing allergic disease with structured environmental exposure as a core study variable.
+4
Try your ownFind ImmPort studies related to [your disease or research area] using a concept or phrase that wouldn't appear as a direct search term.
💬 Q&A
2:10 – 2:25 ET15 min
💬
Open Q&A. Share what you found, what broke, and what you'd like to do next.
🗺️
What's next: Our next ImmPort MCP integration will add data submission tools. We're gathering feedback now on what other tools or workflows you'd want to see — tell us below or reach out anytime.
🧪 Your experience
Did the connection and login work smoothly?
Were the tool responses useful and accurate?
Did anything surprise you — good or bad?
What was the most useful thing you discovered?
🛠 Tool gaps & friction
Were there queries the agent struggled with?
Any data you expected to find but couldn't?
Do the 7 tool names make sense to you?
What would have made the experience smoother?
🚀 What would you do next?
What research questions would you bring to the MCP server?
Would you use this for a specific project or collaboration?
What other ImmPort workflows would benefit from an AI agent?
Data submission tools are next on our roadmap — what else should we prioritize?
Claude doesn't mention ImmPort tools
The integration is not active in this chat. Go to Customize → Connectors → toggle ImmPort ON. Then start a new chat.
❌
Authentication error / "ofid_…" error
Your OAuth session may have expired. Go to Customize → Connectors → disconnect and reconnect ImmPort. Log in again — including completing your MFA prompt.
❌
Download URL doesn't work
Signed URLs expire in ~1 hour. Ask Claude: "Give me a fresh download link for the same file."
⚠️
Claude hits a message limit
Free accounts have a daily cap. If you're rate-limited, try continuing the same conversation thread.
⚠️
"Connectors" option not visible / can't add a custom MCP server
If you're using claude.hhs.gov, the HHS-managed version of Claude does not allow custom MCP connectors. Switch to claude.ai (free account works) to connect to ImmPort MCP.
💡
Claude gives a vague answer
Ask it to be specific: "Show me the exact study accessions" or "List the file names and sizes from the manifest." The more specific your prompt, the more precise the answer.
ImmPort MCP Server Workshop · August 2026 · immport.org
🖥 Appendix — Using Other MCP Clients
💡
This appendix is for participants who want to connect ImmPort MCP to Claude Code or Antigravity outside the workshop. These clients use an ImmPort API key. Claude Desktop users: the web connectors you configure at claude.ai are shared with Claude Desktop automatically — no extra setup needed. If you have Claude Desktop installed, you can use it for the data discovery exercise instead of the browser.
Generate an ImmPort API key (screenshots api-keys/1–2)
API keys are tied to your ImmPort account and expire after 30 days.
Log in at immport.org, click your username in the top-right corner, and select "API Keys" from the dropdown menu
Click "Generate API Key"
Copy the key immediately — it is only shown once — and store it in a safe place (password manager, notes app)
✅ Expected
A long token string starting with eyJ… — this is your API key.
Paste it as the token value in your MCP client config below. Return to this page to generate a new one when it expires.
📸 Generating an ImmPort API Key
A2
Claude Code (CLI)
Add the ImmPort MCP server once — Claude Code stores it in ~/.claude.json and it is available across all projects: