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 synthesises 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 summarises 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 — feel free to ask questions along the way!
🔐
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
Required option
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)
Complete the welcome/registration prompts (screenshots gmail/4–6)
Choose Create ImmPort profile if prompted
Review or complete any required profile fields
Submit to finish account creation/linking
If an account with the same email already exists, choose Link existing account instead of creating a new one.
3
Confirm you can access ImmPort (screenshots gmail/7–8)
After completion, you should land in ImmPort authenticated as your user
If redirected to profile completion, finish required fields and continue
✅ Expected
You're signed into ImmPort and ready to continue with MCP connector setup in Part 2.
📸 ImmPort Sign in with Gmail — step by step
🔑 Optional — Generate Your Own ImmPort API Key
Useful after the workshop
If you'd like to generate your own ImmPort API key for use with Claude Code or Antigravity, follow the steps below.
API keys are tied to your ImmPort account and expire after 30 days.
1
Go to your ImmPort profile (screenshot api-keys/1)
Generate and copy your key (screenshot api-keys/2)
Click "Generate API Key"
Copy the key immediately — it is only shown once
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.
Keys expire after 30 days. Return to this page to generate a new one when it expires.
📸 Generating an ImmPort API Key
🔌 Part 2 — Connect Claude to ImmPort MCP Server
1:35 – 1:45 ET10 min
⏰ Target: 1:45 ET. We'll aim to start the exercise around 1:45.
🖥
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.
1
Log in to claude.ai (screenshot claude/1–3)
Open claude.ai. Click "Continue with Google", select your account — you'll land on the Claude home page.
2
Open Customize → Connectors (screenshot claude/4)
Click the Customize icon in the bottom-left sidebar
Go to the "Connectors" section
Click "Add custom connector"
3
Enter ImmPort connector details (screenshot claude/5)
In the "Add custom connector" dialog:
Name:ImmPort
URL:https://mcp.immport.org
Client ID:immport-mcp-client
Click Save. Claude will open the ImmPort login page in a popup.
4
Log in to ImmPort from the popup (screenshots claude/7–9)
The ImmPort login page opens — enter your username and password
Click Sign In — ImmPort will send an Email OTP to your registered email
Check your email, copy the OTP code, enter it on the MFA page
Click Submit — you'll be redirected back to Claude
5
Confirm connection (screenshot claude/10)
Back in Claude Customize → Connectors, ImmPort should show "Connected ✓" with tool permissions listed.
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:05 ET20 min interactive
⏰ Target: 2:05 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, and download clinical protocol documents — all in plain English, no code.
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–17)
B1
Ask for a deep dive:
PromptDeep dive into SDY998
✅ Expected
Claude calls get_study_data and get_study_data_availability in parallel. Returns: study title (AMP Rheumatoid Arthritis Phase 1), PI consortium (Rochester, Hospital for Special Surgery, Stanford, UCSD…), 62 subjects across 3 arms (RA arthroplasty, OA arthroplasty, RA synovial biopsy), sex breakdown: 44 female (71%), 15 male.
B2
Summarize the study:
PromptSummarize the study.
✅ Expected — screenshot 21
Claude returns a structured summary: SDY998 — AMP Rheumatoid Arthritis Phase 1: A technology-validation study under NIH's AMP RA/SLE program, designed to test whether high-dimensional molecular profiling could distinguish RA from OA in joint tissue.
B3
List available files:
PromptWhat files are available to download for SDY998?
✅ Expected — screenshot 16
Claude calls get_study_files(manifest, SDY998) and returns a file inventory: 1,016 total files — 956 result files (FCS, sequencing), 32 archive files (older data releases), 13 protocol files (SOPs and clinical protocols).
Exercise Step C — Download Clinical Protocol Documents (screenshots 17–20)
C1
Ask for the clinical assessment forms / protocols:
PromptDownload the clinical assessment forms for SDY998.
✅ Expected — screenshots 17–18
Claude lists 13 protocol documents and calls get_study_files(download) for each. It returns signed CloudFront download URLs — one per document. You'll see documents like AMPRA Clinical Protocol Phase 1, AMPRA Clinical Phase 1 Plan, etc.
C2
Click a download link to get the file:
Claude shows a list of signed URLs — click any one
Claude asks "You're leaving Claude to visit an external link" — click Continue(screenshot 19)
The PDF downloads in your browser (screenshot 20 — "329 KB Done")
⚠️
Signed URLs expire in ~1 hour. If a link fails, ask Claude: "Give me a fresh download link."
📸 Data Discovery Exercise — screenshots 12–21
⭐ 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:05 – 2:10 ET5 min
💬
Open Q&A. Share what you found, what broke, and what you'd like to do next.
🧪 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?
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.
Raise your hand or ask the instructor if you get stuck. We're here to help!
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.