ImmPort MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Get Study Files

get_study_files

List, stream, or download ImmPort study files, protocol documents, and result files by study accession; retrieve file manifests and signed URLs for metadata, raw data, or archives.

Instructions

Access ImmPort study files, protocol documents, and result files — list, stream, or download.

action='manifest' — list all files for a study. Required: study_accession (one, or up to 20 separated by commas, e.g. 'SDY1,SDY269'; each record carries studyAccession) Optional: file_type filter — one of: study_file supplemental study documents protocol_file protocol documents result_file individual assay result files (FCS, CEL, txt, gz, etc.) release_file current DR package: Tab zip, MySQL zip, summary, manifest, subject-to-result mapping files archive_file older DR versions as SDY##-DR{n}.zip (Tab + MySQL, no raw files) zip_file SDY##_DR##_ALL_DATA.zip — ALL metadata + ALL raw result files; can be very large (some studies >100 GB); check filesizeBytes first Returns: list of records with fileUUID, fileName, fileType, filesizeBytes, path. Common patterns: Latest Tab metadata zip: file_type='release_file' → find fileName ending '_Tab.zip' Full data + raw files: file_type='zip_file' → SDY##_DR##_ALL_DATA.zip Older DR versions: file_type='archive_file' → SDY##-DR{n}.zip (Tab nested inside)

💡 SPARSE DATA: Many ImmPort studies — particularly older studies and recently released data — have minimal parsed data in the database. The full study detail (protocol design, subject demographics, assay methodology, investigator notes) is often only available in the study files. When get_study_data returns limited results, call manifest with NO file_type filter to see all available files, then: • stream individual study_file / protocol_file documents (plain text / TSV) using action='stream' for inline AI analysis • provide the signed URL for the _Tab.zip (release_file) which contains every study metadata table as a TSV — complete structured data action='download' — get a signed CloudFront URL for a file. Required: file_uuid (fileUUID from manifest) Returns: {'url': ''} ⛔ DO NOT fetch or open this URL yourself — you are running in a sandbox with no network access to CloudFront/S3 and the request will fail. ONLY present the URL to the user so they can download it in their browser or with curl/wget. Your job is done once you return the URL. Use for: zip files, large binaries, any file the user wants to fetch themselves.

action='stream' — fetch file content inline for AI analysis. Required: file_uuid (fileUUID from manifest) Optional: max_bytes (default 2 MB) Returns: {'content': ''} for text/CSV/TSV/JSON files, {'content_base64': '...'} for binary files. ⚠️ Do NOT stream zip files — they are binary and will be truncated uselessly. Use action='download' for any zip file.

⚠️ ImmPort enforces a per-file daily download limit — avoid redundant calls.

Examples: get_study_files('manifest', study_accession='SDY61', file_type='release_file') get_study_files('download', file_uuid='97a310f6-405d-45c9-8ce9-75f7ccac4ffb') get_study_files('stream', file_uuid='325b0667-59d8-4838-8bd7-5b0a5840a3e6')

Input Schema

Name	Required	Description	Default
`action`	Yes
`file_type`	No
`file_uuid`	No
`max_bytes`	No
`study_accession`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.4.0Nov 5, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses signed CloudFront URL behavior, sandbox network limitations, per-file daily download limits, large file sizes, binary truncation risk, and default stream size limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well structured with action headings, bullets, warnings, and examples, and it is front-loaded by action. It is somewhat long and repeats some file_type guidance in the common-patterns section, but the length is largely justified for a complex multi-action tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter, multi-action tool with no annotation coverage and no schema descriptions, the description is complete enough to call correctly. It covers required inputs, action-specific behavior, file-type semantics, limits, examples, and fallback guidance for sparse data; the output schema can handle return-value details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: it explains the action enum values, study_accession accepts one or up to 20 comma-separated accessions, file_type values and meanings, file_uuid sourcing from manifest, and max_bytes default behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: access ImmPort study files, protocol documents, and result files via list, stream, or download. It clearly distinguishes the three action modes and their purposes, so an agent can identify what the tool does without inspecting the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance for each action: manifest for listing, download for signed URLs and large binaries, stream for inline text analysis. It also includes exclusions and alternatives, such as do not stream zip files and do not fetch signed URLs yourself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server