Registry /
aws / awslabs-aws-healthomics-mcp-server
Install & Compatibility
Where this runs
tested against v0.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
474MB installed
● package 474MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HealthOmicsMCPServer
✓ from awslabs.aws_healthomics_mcp_server import HealthOmicsMCPServer
✗ from awslabs.aws_healthomics_mcp_server.server import HealthOmicsMCPServer
This quickstart demonstrates how to implement a basic AWS HealthOmics Model Context Protocol (MCP) server using the SDK. It defines a custom server class inheriting from `HealthOmicsMCPServer`, implements the `get_model_context` method to return model-specific information, and sets up a FastAPI application instance using `create_app`. The resulting `app` can be run with Uvicorn. It includes comments on how to run and test the server locally, along with considerations for AWS authentication.
import os
from typing import Dict, Any
from healthomics_mcp_server.server import HealthOmicsMCPServer
from healthomics_mcp_server.model import ModelContext, ModelContextType
from healthomics_mcp_server.app import create_app
# Configure AWS credentials for boto3 if not using environment variables or instance profiles
# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY_ID')
# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_ACCESS_KEY')
# os.environ['AWS_REGION'] = os.environ.get('AWS_REGION', 'us-east-1')
class MyCustomMCPServer(HealthOmicsMCPServer):
async def get_model_context(self, model_id: str) -> ModelContext:
"""Implement logic to retrieve a model's context based on its ID."""
print(f"[MCP Server] Request received for model context: {model_id}")
# In a real application, you would fetch this from a database, S3, or another service.
# For this example, we return a predefined context based on an environment variable.
if model_id == os.environ.get('EXAMPLE_MODEL_ID', 'example-model-123'):
return ModelContext(
id=model_id,
type=ModelContextType.DEFAULT,
properties={
"workflow_id": "wf-abc123def456",
"reference_genome": "hg38",
"sample_type": "blood"
}
)
# For any other model_id, return a generic or empty context
return ModelContext(
id=model_id,
type=ModelContextType.DEFAULT, # Or another specific type like ModelContextType.EMPTY
properties={}
)
async def get_health(self) -> Dict[str, Any]:
"""Provide health status of the server."""
print("[MCP Server] Health check requested.")
return {"status": "ok", "server_id": "my-omics-server-v1"}
# Instantiate your custom server implementation
server_instance = MyCustomMCPServer()
# Create the FastAPI application instance by passing your server_instance
app = create_app(server_instance)
# --- To run this application: ---
# 1. Save the code above as `main.py`.
# 2. Make sure uvicorn is installed: `pip install awslabs-aws-healthomics-mcp-server[uvicorn]`
# 3. Run from your terminal: `uvicorn main:app --host 0.0.0.0 --port 8000 --reload`
# 4. Access the health endpoint: `http://localhost:8000/health`
# 5. Get model context (replace `example-model-123` with your desired ID):
# `http://localhost:8000/model-context/example-model-123`
# Set EXAMPLE_MODEL_ID in your environment for a specific test: `export EXAMPLE_MODEL_ID=my-custom-model`
Debug
Known issues
breakingAs a pre-1.0 (0.0.x series) library, API interfaces and behaviors may change frequently without strict adherence to semantic versioning. Always review release notes or the GitHub repository when upgrading.fixPin specific patch versions (`==0.0.X`) in your `requirements.txt` and thoroughly test when upgrading. Consult the GitHub repository's `CHANGELOG.md` or commit history for breaking changes.
affects: All versions < 1.0.0
gotchaThe server implementation may interact with AWS HealthOmics or other AWS services (e.g., S3, EC2). Ensure that the IAM role or credentials used by the server have the necessary permissions for these interactions, including `omics:GetRun` or similar actions depending on your model context.fixDefine a fine-grained IAM policy for your server's execution role, granting only the least privilege required. Test permissions thoroughly during development.
affects: All versions
gotchaThis library explicitly requires Pydantic V2 (`pydantic>=2.0`). If your project also uses other FastAPI-based libraries or a legacy FastAPI setup, ensure compatibility. Pydantic V2 introduced significant breaking changes from V1.fixVerify all dependencies are compatible with Pydantic V2. If integrating with existing code, be aware of Pydantic V1 to V2 migration steps (e.g., `Field` vs `FieldInfo`, `BaseModel` changes).
affects: All versions requiring `pydantic>=2.0` (0.0.34 and later)
Upgrade
Version history
0.1.0latest on PyPI · released Aug 26, 2026
Audit
Dependencies
fastapirequiredCore web framework for the MCP server.
uvicornoptionalASGI server for running the FastAPI application. Optional if deploying to other ASGI servers.
pydanticrequiredData validation and settings management, explicitly requires >=2.0.
boto3requiredAWS SDK for Python, used for interacting with AWS services.
requestsrequiredHTTP client library, typically used by boto3 or internal components.
pyyamlrequiredUsed for configuration file parsing.