Getting Started with the MSSP ACO Pipeline
This guide walks through setting up and running the full pipeline, from downloading raw CMS files to running Tuva analytics and calculating projected savings.
The published connector chain still resolves to Tuva Core 0.17.2 through the CCLF dependency file. These instructions describe that connector workflow, not a validated Core 1.0 installation. Before adopting 1.0, update the complete dependency graph, migrate its Input Layer mappings, and validate your source with Input Data Quality. Changing a Core version pin alone does not establish connector compatibility.
Prerequisites
Before you begin, you will need:
- CMS Datahub access — Credentials for the ACO Management System (ACOMS) to download your ACO's data files
- Your ACO ID — The CMS-assigned identifier for your ACO
- An output backend and warehouse profile — Choose a pipeline output backend and separately verify support in each dbt connector you will run. Parquet output is a file format, not a dbt warehouse validation.
- Python 3.11+ and uv for running the MSSP Pipeline
- dbt installed and configured for your data warehouse
Step 1: Go to the CMS Portal and setup API Credentials
Go to the ACO Management System Portal and navigate to the API Credentials tab. Once there, under ACO-MS API Credentials click Create New Credentials, you will need to give the API credential a name (i.e. MSSP Data Pipeline), then select Credential delegate (API) for the API Key access level and Data Hub as the Resource. You will also need to input the IP address of the machine that will be running the MSSP pipeline.
Store the API credentials in a safe location to be used in a later step.
Step 2: Download and Load CMS Data
Next we will need to clone the MSSP Pipeline and configure its dependencies and credentials. The MSSP pipeline does the heavy lifting by downloading, unpacking the ACO's files from the CMS Datahub and then loads them into your data warehouse.
Clone and configure the MSSP Pipeline
git clone https://github.com/tuva-health/cms_mssp_pipeline.git mssp_pipeline
cd mssp_pipeline
Install dependencies
Example of installing dependencies, see MSSP Pipeline for more options depending on your cloud provider and warehouse.
# Install with your desired output backend, e.g. Snowflake:
uv sync --extra processing --extra snowflake
Configure API credentials (one-time)
This launches the ACOMS CLI and asks you to save the ACO-MS API Credentials we acquired earlier.
uv run mssp-download --configure
Edit .env with connection info
Next we need to configure the MSSP Pipeline with information on what ACO ID we will be transmitting data for, and what MSSP_FILE_STORE and MSSP_OUTPUT_TYPE to use in the integrations.
MSSP_ACO_ID=A1234
MSSP_FILE_STORE=s3://my/mssp/data/location
MSSP_OUTPUT_TYPE=SNOWFLAKE
Next, add configuration for your warehouse connection settings in the same file (e.g., SNOWFLAKE_ACCOUNT, SNOWFLAKE_DATABASE, etc.). See the MSSP Pipeline page for a full list of configurations for the supported data warehouses.
Run the pipeline
# Download files from CMS Datahub Only
uv run mssp-download
# Take already downloaded files and transform and load to your warehouse
uv run mssp-process
# Or run both in sequence
uv run mssp-pipeline
After this step, your warehouse will contain raw CCLF tables, ALR tables, and other MSSP data files.
Step 3: Run the CMS MSSP Connector
The CMS MSSP Connector runs immediately after the pipeline to build source objects and intermediate models for all MSSP report files that are not ALR or CCLF (benchmark expenditures, quality measures, shadow bundles, non-claims payments, and more).
Clone and configure the CMS MSSP Connector
git clone https://github.com/tuva-health/cms_mssp_connector.git
cd cms_mssp_connector
Install dependencies
uv sync
Configure
In cms_mssp_connector/dbt_project.yml, update the config to point to the raw MSSP source data:
vars:
input_database: "your_database"
input_schema: "your_mssp_schema"
Run the CMS MSSP Connector
uv run dbt deps
uv run dbt build
This creates staging and intermediate models for the MSSP report files. The MSSP connector also runs the ALR and CCLF connectors to populate the Tuva Input Layer. The existing dependency chain installs legacy Core. A Core 1.0 deployment requires replacing that chain with a validated, compatible root-owned package graph and explicitly installing the selected standalone packages.
Step 4: Deploy ACO dashboards (Tuva 0.18 only)
The currently published CMS ACO Power BI dashboards depend on the Tuva 0.18 data marts and legacy Semantic Layer. If you are running Tuva 0.18, follow the instructions on the CMS ACO Dashboards page. Do not deploy this dashboard workflow against Tuva 1.0 until a compatible version is published.
Pipeline Summary
| Step | Tool | Input | Output |
|---|---|---|---|
| 1 | mssp_pipeline | CMS Datahub | All raw MSSP tables in warehouse |
| 2 | cms_mssp_connector (phase 1) | Raw MSSP tables | Staging + intermediate MSSP models |
| 3 | cms_alr_connector | ALR tables | enrollment table |
| 4 | medicare_cclf_connector | CCLF tables + enrollment | eligibility, medical_claim, pharmacy_claim |
| 5 | Tuva Core + selected standalone packages | Tuva Input Layer | Core Data Model + explicitly installed package outputs |
| 6 (Tuva 0.18 only) | Legacy MSSP ACO Power BI Dashboards | Tuva 0.18 data marts + legacy Semantic Layer | Power BI dashboards |