AWS HealthOmics

AWS HealthOmics MCP Server

Generate, run, debug lifescience workflows.

What is an MCP Server?⁠

MCP Info

Image Building Info

Attribute	Details
Dockerfile	https://github.com/awslabs/mcp/blob/636aca8e109b5559006044f035bb89c16e9e5410/src/aws-healthomics-mcp-server/Dockerfile⁠
Commit	636aca8e109b5559006044f035bb89c16e9e5410
Docker Image built by	Docker Inc.
Docker Scout Health Score
Verify Signature	COSIGN_REPOSITORY=mcp/signatures cosign verify mcp/aws-healthomics-mcp-server --key https://raw.githubusercontent.com/docker/keyring/refs/heads/main/public/mcp/latest.pub
Licence	Apache License 2.0

Available Tools (73)

Tools Details

Tool: ActivateAHOReadSets

Activate archived read sets in a HealthOmics sequence store.

Starts an activation job to move read sets from archive storage back to active storage.

Tool: AnalyzeAHORunPerformance

Analyze AWS HealthOmics workflow run performance and provide optimization recommendations.

This tool analyzes HealthOmics workflow runs to help users optimize:

• Resource utilization patterns (CPU, memory)
• Cost optimization opportunities
• Performance bottlenecks
• Resource allocation efficiency
• Runtime optimization suggestions

Use this tool when users ask about:

• "How can I optimize my HealthOmics runs?"
• "Why is my workflow using too many resources?"
• "How can I reduce costs for my genomic workflows?"
• "What resources are being wasted in my runs?"
• "How can I improve workflow performance?"

The tool summarizes run manifest logs containing task-level metrics and provides a structured report with recommendations for optimization.

Tool: CancelAHORunBatch

Cancel all runs in a HealthOmics batch.

Tool: CheckContainerAvailability

Check if a container image is available in ECR and accessible by HealthOmics.

Queries ECR to determine if a specific container image exists in a repository and whether HealthOmics has the required permissions to pull the image. For pull-through cache repositories, indicates that the image may be pulled on first access even if not currently cached.

When initiate_pull_through is True and the image is not found in a pull-through cache repository that is accessible to HealthOmics, this function will attempt to initiate the pull-through using ECR's batch_get_image API call. This triggers ECR to pull the image from the upstream registry and cache it locally.

Tool: CloneContainerToECR

Clone a container image to a private ECR repository for HealthOmics use.

This tool copies a container image from an upstream registry (Docker Hub, Quay.io, ECR Public) to your private ECR repository with appropriate HealthOmics access permissions. It uses ECR pull-through cache to perform the copy.

The tool will:

1. Parse the source image reference (handling Docker Hub shorthand like "ubuntu:latest")
2. Find an existing pull-through cache rule for the source registry
3. Use the pull-through cache to pull the image into ECR
4. Grant HealthOmics access permissions to the repository
5. Return the ECR URI and digest for use in workflows

Image reference formats supported:

• "ubuntu:latest" -> registry-1.docker.io/library/ubuntu:latest
• "myorg/myimage:v1" -> registry-1.docker.io/myorg/myimage:v1
• "quay.io/biocontainers/samtools:1.17" -> quay.io/biocontainers/samtools:1.17
• "public.ecr.aws/lts/ubuntu:22.04" -> public.ecr.aws/lts/ubuntu:22.04 Parameters|Type|Description -|-|- source_image|string|Source container image reference (e.g., "ubuntu:latest", "myorg/myimage:v1", "quay.io/org/image:tag") aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. target_image_tag|stringoptional|Target image tag. If not provided, uses source tag or "latest". target_repository_name|stringoptional|Target ECR repository name. Only used if no pull-through cache exists. If not provided, derives from source image.

Tool: CreateAHOConfiguration

Create a new HealthOmics configuration.

Tool: CreateAHORunCache

Create a new HealthOmics run cache.

Tool: CreateAHORunGroup

Create a new HealthOmics run group.

Tool: CreateAHOSequenceStore

Create a new HealthOmics sequence store.

Tool: CreateAHOWorkflow

Create a new HealthOmics workflow.

Tool: CreateAHOWorkflowVersion

Create a new version of an existing workflow.

Tool: CreateCodeConnection

Create a new CodeConnection.

This function creates a new AWS CodeConnection for connecting to a third-party Git provider. The connection will be created in PENDING status and requires OAuth authorization in the AWS Console to become AVAILABLE.

Tool: CreateContainerRegistryMap

Create a container registry map for HealthOmics workflows.

Creates a container registry map file that can be used when creating HealthOmics workflows. Registry mappings allow workflows to use container images from upstream registries (Docker Hub, Quay.io, ECR Public) without modifying the workflow definition. The mappings redirect container pulls to your private ECR pull-through caches.

By default, this tool discovers all HealthOmics-usable pull-through cache rules in your ECR registry and creates mappings for them. You can also provide additional registry mappings or specific image mappings for container overrides.

Tool: CreatePullThroughCacheForHealthOmics

Create a pull-through cache rule configured for HealthOmics.

Creates an ECR pull-through cache rule for the specified upstream registry and configures the necessary permissions for HealthOmics to use it. This includes:

1. Creating the pull-through cache rule
2. Updating the registry permissions policy to allow HealthOmics to create repositories and import images
3. Creating a repository creation template that grants HealthOmics the required permissions to pull images Parameters|Type|Description -|-|- upstream_registry|string|Upstream registry type: docker-hub, quay, or ecr-public aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. credential_arn|stringoptional|Secrets Manager ARN for registry credentials (required for docker-hub) ecr_repository_prefix|stringoptional|ECR repository prefix (defaults to registry type name)

Tool: DeleteAHOBatch

Delete a HealthOmics batch metadata (does not delete runs).

Tool: DeleteAHOConfiguration

Delete a HealthOmics configuration.

Tool: DeleteAHORunBatch

Delete all runs in a HealthOmics batch.

Tool: DiagnoseAHORunFailure

Provides comprehensive diagnostic information for a failed workflow run.

This function collects multiple sources of diagnostic information including:

• Run details and failure reason
• Engine logs from CloudWatch
• Run manifest logs containing workflow summary and resource metrics (when detailed=True)
• Task logs from all failed tasks
• Actionable recommendations for troubleshooting Parameters|Type|Description -|-|- run_id|string|ID of the failed run aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. detailed|booleanoptional|If False, excludes manifest logs and limits engine/task logs to last 50 lines from 15 minutes before stop time to 5 minutes after. If True, includes all logs. False is suitable for most scenarios

Tool: GenerateAHORunTimeline

Generate a Gantt-style timeline visualization for an AWS HealthOmics workflow run.

This tool creates an SVG Gantt chart showing task execution phases (pending and running) with status-based coloring. The chart helps visualize task parallelism and identify bottlenecks in workflow execution.

Use this tool when users ask about:

• "Show me a timeline of my workflow run"
• "Visualize the execution of my HealthOmics workflow"
• "Create a Gantt chart for my run"
• "How did my tasks execute over time?"
• "What was the parallelism in my workflow?"

The chart displays:

• Pending/starting phase (light grey bars)
• Running phase (colored by status: blue=COMPLETED, red=FAILED, orange=CANCELLED)
• Interactive tooltips with task details (name, CPUs, memory, instance type, cost)
• Time axis with configurable units (seconds, minutes, hours, days) Parameters|Type|Description -|-|- run_id|string|The run ID to generate timeline for. aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. expected_bucket_owner|stringoptional|AWS account ID that must own the target S3 bucket. Defaults to the current caller identity account ID. Set to None to skip bucket owner verification. Only used when output_path is an S3 URI. output_format|stringoptional|Output format for the timeline. Valid values: svg (raw SVG string, default), base64 (base64-encoded SVG, useful when transport safety is needed to avoid XML/SVG markup mangling in JSON or other text protocols; note the output must be base64-decoded before it can be rendered as SVG). Use svg when writing to a local or s3 path. Defaults to svg. output_path|stringoptional|Optional file path or S3 URI (s3://bucket/key) where the SVG output will be written. When provided, the response contains only summary metadata instead of the full SVG content. Recommended for complex workflows to avoid context window overflow. region|stringoptional|AWS region for pricing lookups. Defaults to us-east-1. theme|stringoptional|Color theme for the timeline visualization. Valid values: light, dark. Use dark for better legibility on dark backgrounds. Defaults to light. time_unit|stringoptional|Time unit for the timeline axis. Valid values: sec, min, hr, day. Defaults to hr.

Tool: GetAHOBatch

Get details of a specific HealthOmics batch.

Tool: GetAHOConfiguration

Get details of a specific HealthOmics configuration.

Tool: GetAHOReadSetExportJob

Get details about a read set export job.

Tool: GetAHOReadSetImportJob

Get details about a read set import job.

Tool: GetAHOReadSetMetadata

Get metadata for a specific read set in a HealthOmics sequence store.

Tool: GetAHOReferenceImportJob

Get details about a reference import job.

AWS HealthOmics allows only one reference store per account per region. If reference_store_id is not provided, it will be automatically resolved.

Tool: GetAHOReferenceMetadata

Get metadata for a specific reference in a HealthOmics reference store.

AWS HealthOmics allows only one reference store per account per region. If reference_store_id is not provided, it will be automatically resolved.

Tool: GetAHOReferenceStore

Get details about a specific HealthOmics reference store.

AWS HealthOmics allows only one reference store per account per region. If reference_store_id is not provided, it will be automatically resolved.

Tool: GetAHORun

Get details about a specific run.

Tool: GetAHORunCache

Get details of a specific HealthOmics run cache.

Tool: GetAHORunEngineLogs

Retrieve engine logs containing STDOUT and STDERR from the workflow engine process.

These logs contain all output from the workflow engine process including:

• Engine startup and initialization messages
• Workflow parsing and validation output
• Task scheduling and execution messages
• Error messages and debugging information Parameters|Type|Description -|-|- run_id|string|ID of the run aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. end_time|stringoptional|Optional end time for log retrieval (ISO format) limit|integeroptional|Maximum number of log events to return next_token|stringoptional|Token for pagination from a previous response start_from_head|booleanoptional|Whether to start from the beginning (True) or end (False) of the log stream start_time|stringoptional|Optional start time for log retrieval (ISO format)

Tool: GetAHORunGroup

Get details of a specific HealthOmics run group.

Tool: GetAHORunLogs

Retrieve high-level run logs that show workflow execution events.

These logs contain a high-level summary of events during a run including:

• Run creation and start events
• File import start and completion
• Workflow task start and completion
• Export start and completion
• Workflow completion Parameters|Type|Description -|-|- run_id|string|ID of the run aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. end_time|stringoptional|Optional end time for log retrieval (ISO format) limit|integeroptional|Maximum number of log events to return next_token|stringoptional|Token for pagination from a previous response start_from_head|booleanoptional|Whether to start from the beginning (True) or end (False) of the log stream start_time|stringoptional|Optional start time for log retrieval (ISO format)

Tool: GetAHORunManifestLogs

Retrieve run manifest logs produced when a workflow completes or fails.

These logs contain a summary of the overall workflow including:

• Runtime information
• Inputs and input digests
• Messages and status information
• Task summaries with resource allocation and utilization metrics Parameters|Type|Description -|-|- run_id|string|ID of the run run_uuid|string|Optional UUID of the run aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. end_time|stringoptional|Optional end time for log retrieval (ISO format) limit|integeroptional|Maximum number of log events to return next_token|stringoptional|Token for pagination from a previous response start_from_head|booleanoptional|Whether to start from the beginning (True) or end (False) of the log stream start_time|stringoptional|Optional start time for log retrieval (ISO format)

Tool: GetAHORunTask

Get details about a specific task.

Tool: GetAHOSequenceStore

Get details about a specific HealthOmics sequence store.

Tool: GetAHOSupportedRegions

Get the list of AWS regions where HealthOmics is available.

Tool: GetAHOTaskLogs

Retrieve logs for a specific workflow task containing STDOUT and STDERR.

These logs contain the output from a specific task process including:

• Task container startup messages
• Application-specific output and error messages
• Task completion or failure information Parameters|Type|Description -|-|- run_id|string|ID of the run task_id|string|ID of the specific task aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. end_time|stringoptional|Optional end time for log retrieval (ISO format) limit|integeroptional|Maximum number of log events to return next_token|stringoptional|Token for pagination from a previous response start_from_head|booleanoptional|Whether to start from the beginning (True) or end (False) of the log stream start_time|stringoptional|Optional start time for log retrieval (ISO format)

Tool: GetAHOWorkflow

Get details about a specific workflow.

Tool: GetCodeConnection

Get details about a specific CodeConnection.

This function retrieves detailed information about a specific AWS CodeConnection, including its current status and guidance on next steps. Use this to check if a connection is ready for use with HealthOmics workflows or if OAuth authorization is still required.

Tool: GetSupportedFileTypes

Get information about supported genomics file types.

Tool: GrantHealthOmicsRepositoryAccess

Grant HealthOmics access to an ECR repository.

Updates the repository policy to allow the HealthOmics service principal (omics.amazonaws.com) to pull images. This adds the required permissions:

• ecr:BatchGetImage
• ecr:GetDownloadUrlForLayer

If the repository already has a policy, the HealthOmics permissions are added while preserving existing statements. If no policy exists, a new policy is created.

Tool: LintAHOWorkflowBundle

Lint multi-file WDL or CWL workflow bundles and return validation findings.

This tool validates multi-file workflow bundles using appropriate linting tools:

• WDL workflows: Uses miniwdl package for parsing and validation with import support
• CWL workflows: Uses cwltool package for parsing and validation with dependency resolution

The tool creates a temporary directory structure that preserves the relative file paths, allowing proper resolution of imports and dependencies between workflow files.

The tool checks for:

• Syntax errors and parsing issues across all files
• Missing required fields (inputs, outputs, steps)
• Import/dependency resolution
• Runtime requirements for tasks
• Common workflow structure issues Parameters|Type|Description -|-|- main_workflow_file|string|Path to the main workflow file within the bundle workflow_files|string|Dictionary mapping file paths to their content, a local directory path, a ZIP file path, or an S3 URI (s3://bucket/prefix/ or s3://bucket/file.zip). workflow_format|string|The workflow format: 'wdl' or 'cwl'

Tool: LintAHOWorkflowDefinition

Lint WDL or CWL workflow definitions and return validation findings.

This tool validates workflow definitions using appropriate linting tools:

• WDL workflows: Uses miniwdl package for parsing and validation
• CWL workflows: Uses cwltool package for parsing and validation

The tool checks for:

• Syntax errors and parsing issues
• Missing required fields (inputs, outputs, steps)
• Runtime requirements for tasks
• Common workflow structure issues Parameters|Type|Description -|-|- workflow_content|string|The workflow definition content to lint. Accepts inline content, a local file path, or an S3 URI (s3://bucket/key). workflow_format|string|The workflow format: 'wdl' or 'cwl' filename|stringoptional|Optional filename for context

Tool: ListAHOBatches

List HealthOmics batches.

Tool: ListAHOConfigurations

List HealthOmics configurations.

Tool: ListAHOReadSetExportJobs

List read set export jobs for a sequence store.

Tool: ListAHOReadSetImportJobs

List read set import jobs for a sequence store.

Tool: ListAHOReadSets

List read sets in a HealthOmics sequence store with optional filtering.

Tool: ListAHOReferenceImportJobs

List reference import jobs for a reference store.

AWS HealthOmics allows only one reference store per account per region. If reference_store_id is not provided, it will be automatically resolved.

Tool: ListAHOReferenceStores

List HealthOmics reference stores.

Tool: ListAHOReferences

List references in a HealthOmics reference store with optional filtering.

AWS HealthOmics allows only one reference store per account per region. If reference_store_id is not provided, it will be automatically resolved.

Tool: ListAHORunCaches

List HealthOmics run caches.

Tool: ListAHORunGroups

List HealthOmics run groups.

Tool: ListAHORunTasks

List tasks for a specific run.

Tool: ListAHORuns

List workflow runs.

Tool: ListAHORunsInBatch

List runs within a HealthOmics batch.

Tool: ListAHOSequenceStores

List HealthOmics sequence stores.

Tool: ListAHOWorkflowVersions

List versions of a workflow.

Tool: ListAHOWorkflows

List available HealthOmics workflows.

Tool: ListCodeConnections

List available CodeConnections.

This function retrieves existing CodeConnections that can be used with HealthOmics workflows. Connections can be filtered by provider type and results are paginated.

Tool: ListECRRepositories

List ECR repositories with HealthOmics accessibility status.

Lists all ECR repositories in the current region and checks each repository's policy to determine if HealthOmics has the required permissions to pull images.

Tool: ListPullThroughCacheRules

List pull-through cache rules with HealthOmics usability status.

Lists all ECR pull-through cache rules in the current region and evaluates each rule's usability by HealthOmics. A pull-through cache is usable by HealthOmics if:

1. The registry permissions policy grants HealthOmics the required permissions
2. A repository creation template exists for the prefix
3. The template grants HealthOmics the required image pull permissions Parameters|Type|Description -|-|- aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. max_results|integeroptional|Maximum number of results to return next_token|stringoptional|Pagination token from a previous response

Tool: PackageAHOWorkflow

Package workflow definition files into a base64-encoded ZIP.

Tool: SearchGenomicsFiles

Search for genomics files across S3 buckets, HealthOmics sequence stores, and reference stores.

This tool provides intelligent search capabilities with pattern matching, file association detection, and ranked results based on relevance scoring. It can find genomics files across multiple storage locations and automatically group related files together.

Tool: StartAHOReadSetExportJob

Start a read set export job to export read sets from a sequence store to S3.

Tool: StartAHOReadSetImportJob

Start a read set import job to import genomic files from S3 into a sequence store.

Tool: StartAHOReferenceImportJob

Start a reference import job to import reference files from S3 into a reference store.

AWS HealthOmics allows only one reference store per account per region. If reference_store_id is not provided, it will be automatically resolved.

Each source in the sources list is validated against the ReferenceImportSource model and must include:

• sourceFile: S3 URI pointing to a FASTA reference file (e.g. "s3://bucket/GRCh38.fasta")
• name: A name for the reference (e.g. "GRCh38")
• description (optional): A description of the reference
• tags (optional): Key-value tags as {"key": "value"}

Example sources JSON: [{"sourceFile": "s3://bucket/GRCh38.fasta", "name": "GRCh38", "description": "Human reference genome build 38", "tags": {"build": "38", "species": "human"}}]

Tool: StartAHORun

Start a workflow run.

   All non-optional parameters must be present, if they are not provided the workflow run will not start. No other parameter names are allowed.
   The descriptions of the parameters in the parameter template may provide clues to the type of the parameter. It may be
   necessary to inspect the workflow definition to determine the appropriate parameter type.
   

role_arn|string|ARN of the IAM role to use for the run workflow_id|string|ID of the workflow to run aws_profile|stringoptional|AWS profile name for this operation. Overrides the default credential chain. aws_region|stringoptional|AWS region for this operation. Overrides the server default. cache_behavior|stringoptional|Optional cache behavior (CACHE_ALWAYS or CACHE_ON_FAILURE) cache_id|stringoptional|Optional ID of a run cache to use configuration_name|stringoptional|Configuration name (required when networking_mode is VPC) networking_mode|stringoptional|Networking mode: RESTRICTED (default) or VPC run_group_id|stringoptional|Optional ID of a run group to associate with this run scratch_storage_mode|stringoptional|Scratch storage mode for the run. Allowed values: LOCAL (mount local EBS ephemeral scratch storage at /tmp for CPU tasks) or SHARED (use shared scratch storage). Defaults to LOCAL when omitted (the MCP server default; note the HealthOmics API default is SHARED). storage_capacity|stringoptional|Storage capacity in GB (required for STATIC). Storage is allocated in 1200 GiB chunks storage_type|stringoptional|Storage type (STATIC or DYNAMIC). DYNAMIC is preferred except for runs with very large inputs (TiBs). workflow_version_name|stringoptional|Optional version name to run

Tool: StartAHORunBatch

Start a new HealthOmics run batch.

Tool: UpdateAHORunCache

Update an existing HealthOmics run cache.

Tool: UpdateAHORunGroup

Update an existing HealthOmics run group.

Tool: UpdateAHOSequenceStore

Update a HealthOmics sequence store.

Internally fetches the current ETag before performing the update to handle optimistic concurrency control.

Tool: ValidateHealthOmicsECRConfig

Validate ECR configuration for HealthOmics workflows.

Performs a comprehensive validation of the ECR configuration to ensure HealthOmics workflows can access container images through pull-through caches. This includes checking:

1. All pull-through cache rules in the region
2. Registry permissions policy for HealthOmics principal
3. Repository creation templates for each pull-through cache prefix
4. Template permissions include required actions

For each issue found, provides specific remediation steps.

Use this MCP Server

{
  "mcpServers": {
    "aws-healthomics": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "AWS_REGION",
        "-e",
        "AWS_PROFILE",
        "mcp/aws-healthomics-mcp-server"
      ],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default"
      }
    }
  }
}

Why is it safer to run MCP Servers with Docker?⁠