{"id":5121,"library":"awslabs-aws-healthomics-mcp-server","title":"AWS HealthOmics Model Context Protocol Server SDK","description":"The `awslabs-aws-healthomics-mcp-server` library provides a Python SDK for implementing the AWS HealthOmics Model Context Protocol (MCP) server. It enables developers to build custom servers that interact with AWS HealthOmics workflows, leveraging FastAPI for the web service aspect. Currently at version `0.0.34`, it is an AWS Labs project in active development, with releases potentially occurring frequently due to its early versioning.","status":"active","version":"0.0.34","language":"en","source_language":"en","source_url":"https://github.com/awslabs/aws-healthomics-mcp-server-sdk","tags":["aws","healthomics","genomics","bioinformatics","server","mcp","protocol","fastapi","sdk"],"install":[{"cmd":"pip install awslabs-aws-healthomics-mcp-server","lang":"bash","label":"Install core library"},{"cmd":"pip install awslabs-aws-healthomics-mcp-server[uvicorn]","lang":"bash","label":"Install with Uvicorn (recommended for local development)"}],"dependencies":[{"reason":"Core web framework for the MCP server.","package":"fastapi"},{"reason":"ASGI server for running the FastAPI application. Optional if deploying to other ASGI servers.","package":"uvicorn","optional":true},{"reason":"Data validation and settings management, explicitly requires >=2.0.","package":"pydantic"},{"reason":"AWS SDK for Python, used for interacting with AWS services.","package":"boto3"},{"reason":"HTTP client library, typically used by boto3 or internal components.","package":"requests"},{"reason":"Used for configuration file parsing.","package":"pyyaml"}],"imports":[{"note":"Base class for implementing the custom MCP server logic.","symbol":"HealthOmicsMCPServer","correct":"from healthomics_mcp_server.server import HealthOmicsMCPServer"},{"note":"Function to initialize the FastAPI application with a custom MCP server instance.","symbol":"create_app","correct":"from healthomics_mcp_server.app import create_app"},{"note":"Data model for representing a HealthOmics model context.","symbol":"ModelContext","correct":"from healthomics_mcp_server.model import ModelContext"},{"note":"Enum for defining the type of model context.","symbol":"ModelContextType","correct":"from healthomics_mcp_server.model import ModelContextType"}],"quickstart":{"code":"import os\nfrom typing import Dict, Any\nfrom healthomics_mcp_server.server import HealthOmicsMCPServer\nfrom healthomics_mcp_server.model import ModelContext, ModelContextType\nfrom healthomics_mcp_server.app import create_app\n\n# Configure AWS credentials for boto3 if not using environment variables or instance profiles\n# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY_ID')\n# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_ACCESS_KEY')\n# os.environ['AWS_REGION'] = os.environ.get('AWS_REGION', 'us-east-1')\n\nclass MyCustomMCPServer(HealthOmicsMCPServer):\n    async def get_model_context(self, model_id: str) -> ModelContext:\n        \"\"\"Implement logic to retrieve a model's context based on its ID.\"\"\"\n        print(f\"[MCP Server] Request received for model context: {model_id}\")\n        \n        # In a real application, you would fetch this from a database, S3, or another service.\n        # For this example, we return a predefined context based on an environment variable.\n        if model_id == os.environ.get('EXAMPLE_MODEL_ID', 'example-model-123'):\n            return ModelContext(\n                id=model_id,\n                type=ModelContextType.DEFAULT,\n                properties={\n                    \"workflow_id\": \"wf-abc123def456\",\n                    \"reference_genome\": \"hg38\",\n                    \"sample_type\": \"blood\"\n                }\n            )\n        \n        # For any other model_id, return a generic or empty context\n        return ModelContext(\n            id=model_id,\n            type=ModelContextType.DEFAULT, # Or another specific type like ModelContextType.EMPTY\n            properties={}\n        )\n\n    async def get_health(self) -> Dict[str, Any]:\n        \"\"\"Provide health status of the server.\"\"\"\n        print(\"[MCP Server] Health check requested.\")\n        return {\"status\": \"ok\", \"server_id\": \"my-omics-server-v1\"}\n\n# Instantiate your custom server implementation\nserver_instance = MyCustomMCPServer()\n\n# Create the FastAPI application instance by passing your server_instance\napp = create_app(server_instance)\n\n# --- To run this application: ---\n# 1. Save the code above as `main.py`.\n# 2. Make sure uvicorn is installed: `pip install awslabs-aws-healthomics-mcp-server[uvicorn]`\n# 3. Run from your terminal: `uvicorn main:app --host 0.0.0.0 --port 8000 --reload`\n# 4. Access the health endpoint: `http://localhost:8000/health`\n# 5. Get model context (replace `example-model-123` with your desired ID):\n#    `http://localhost:8000/model-context/example-model-123`\n#    Set EXAMPLE_MODEL_ID in your environment for a specific test: `export EXAMPLE_MODEL_ID=my-custom-model`\n","lang":"python","description":"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."},"warnings":[{"fix":"Pin 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.","message":"As 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.","severity":"breaking","affected_versions":"All versions < 1.0.0"},{"fix":"Define a fine-grained IAM policy for your server's execution role, granting only the least privilege required. Test permissions thoroughly during development.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify 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).","message":"This 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.","severity":"gotcha","affected_versions":"All versions requiring `pydantic>=2.0` (0.0.34 and later)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}