Medicaid MCP Server

Instructions

Implementation Reference

• src/index.js:159-241 (handler)

  Primary handler for executing the 'medicaid_info' tool. Checks tool name, extracts method from arguments, dispatches to specific helper functions based on method, formats JSON response or error.

  // Handle tool calls
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    if (name !== 'medicaid_info') {
      throw new Error(`Unknown tool: ${name}`);
    }
  
    try {
      const { method, ...params } = args;
  
      let result;
  
      switch (method) {
        case 'get_nadac_pricing':
          result = await getNADACPricing(params);
          break;
  
        case 'compare_drug_pricing':
          result = await compareDrugPricing(params);
          break;
  
        case 'get_enrollment_trends':
          result = await getEnrollmentTrends(params);
          break;
  
        case 'compare_state_enrollment':
          result = await compareStateEnrollment(params);
          break;
  
        case 'get_drug_rebate_info':
          result = await getDrugRebateInfo(params);
          break;
  
        case 'search_state_formulary':
          result = await searchStateFormulary(params);
          break;
  
        case 'get_drug_utilization':
          result = await queryDrugUtilization(params);
          break;
  
        case 'get_federal_upper_limits':
          result = await queryFederalUpperLimits(params);
          break;
  
        case 'list_available_datasets':
          result = await listAvailableDatasets();
          break;
  
        case 'search_datasets':
          result = await searchDatasets(params);
          break;
  
        default:
          throw new Error(`Unknown method: ${method}`);
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
  
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: error.message,
              method: args.method,
              params: args
            }, null, 2)
          }
        ],
        isError: true
      };
    }
  });

• src/index.js:38-154 (schema)

  Detailed input schema for the 'medicaid_info' tool, defining the 'method' enum and all supporting parameters for Medicaid data queries.

  {
    name: 'medicaid_info',
    description: 'Unified tool for Medicaid data operations: access enrollment trends, drug pricing (NADAC), quality measures, and program performance from data.medicaid.gov via Socrata SODA API. Provides state-level aggregates (NOT provider-level like Medicare).',
    inputSchema: {
      type: 'object',
      properties: {
        method: {
          type: 'string',
          enum: [
            'get_nadac_pricing',
            'compare_drug_pricing',
            'get_enrollment_trends',
            'compare_state_enrollment',
            'get_drug_rebate_info',
            'search_state_formulary',
            'get_drug_utilization',
            'get_federal_upper_limits',
            'list_available_datasets',
            'search_datasets'
          ],
          description: 'The operation to perform: get_nadac_pricing (drug pricing), compare_drug_pricing (multi-drug comparison), get_enrollment_trends (state enrollment), compare_state_enrollment (multi-state comparison), get_drug_rebate_info (rebate program), search_state_formulary (CA/NY/TX/OH/IL formularies), get_drug_utilization (state prescriptions), get_federal_upper_limits (FUL pricing), list_available_datasets (catalog), search_datasets (custom query)',
          examples: ['get_nadac_pricing', 'search_state_formulary', 'get_drug_rebate_info']
        },
        state: {
          type: 'string',
          description: 'State abbreviation (e.g., "CA", "TX", "NY") - required for get_enrollment_trends',
          examples: ['CA', 'TX', 'NY', 'FL', 'PA']
        },
        states: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of state abbreviations for compare_state_enrollment',
          examples: [['CA', 'TX', 'NY'], ['FL', 'PA', 'IL']]
        },
        ndc_code: {
          type: 'string',
          description: 'National Drug Code (11-digit) for get_nadac_pricing',
          examples: ['00002-7510-01', '00169-7501-11']
        },
        drug_name: {
          type: 'string',
          description: 'Drug name (partial match supported) for get_nadac_pricing or get_drug_rebate_info',
          examples: ['semaglutide', 'insulin', 'metformin']
        },
        price_date: {
          type: 'string',
          description: 'Specific pricing date (YYYY-MM-DD) for get_nadac_pricing - defaults to latest',
          examples: ['2024-12-11', '2024-01-01']
        },
        start_date: {
          type: 'string',
          description: 'Start date (YYYY-MM-DD) for time-range queries',
          examples: ['2023-01-01', '2024-01-01']
        },
        end_date: {
          type: 'string',
          description: 'End date (YYYY-MM-DD) for time-range queries',
          examples: ['2024-12-01', '2024-12-31']
        },
        enrollment_type: {
          type: 'string',
          enum: ['total', 'medicaid', 'chip', 'adult', 'child'],
          description: 'Type of enrollment data for enrollment methods',
          examples: ['total', 'medicaid', 'chip']
        },
        month: {
          type: 'string',
          description: 'Specific month (YYYY-MM) for compare_state_enrollment',
          examples: ['2024-09', '2024-01']
        },
        ndc_codes: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of NDC codes for compare_drug_pricing',
          examples: [['00002-7510-01', '00169-7501-11']]
        },
        drug_names: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of drug names for compare_drug_pricing',
          examples: [['semaglutide', 'dulaglutide']]
        },
        labeler_name: {
          type: 'string',
          description: 'Manufacturer name for get_drug_rebate_info',
          examples: ['Novo Nordisk', 'Pfizer']
        },
        rebate_year: {
          type: 'integer',
          description: 'Year for get_drug_rebate_info',
          examples: [2024, 2023]
        },
        dataset_id: {
          type: 'string',
          description: 'Dataset identifier for search_datasets',
          examples: ['99315a95-37ac-4eee-946a-3c523b4c481e']
        },
        where_clause: {
          type: 'string',
          description: 'SoQL WHERE clause for search_datasets',
          examples: ["state='CA' AND year=2024"]
        },
        limit: {
          type: 'integer',
          description: 'Maximum results to return (default: 100, max: 5000)',
          examples: [100, 500, 1000]
        },
        offset: {
          type: 'integer',
          description: 'Pagination offset (default: 0)',
          examples: [0, 100, 200]
        }
      },
      required: ['method'],
      additionalProperties: false
    }
  }

• src/index.js:35-157 (registration)

  Registers the 'medicaid_info' tool for listing in MCP tool discovery.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: 'medicaid_info',
          description: 'Unified tool for Medicaid data operations: access enrollment trends, drug pricing (NADAC), quality measures, and program performance from data.medicaid.gov via Socrata SODA API. Provides state-level aggregates (NOT provider-level like Medicare).',
          inputSchema: {
            type: 'object',
            properties: {
              method: {
                type: 'string',
                enum: [
                  'get_nadac_pricing',
                  'compare_drug_pricing',
                  'get_enrollment_trends',
                  'compare_state_enrollment',
                  'get_drug_rebate_info',
                  'search_state_formulary',
                  'get_drug_utilization',
                  'get_federal_upper_limits',
                  'list_available_datasets',
                  'search_datasets'
                ],
                description: 'The operation to perform: get_nadac_pricing (drug pricing), compare_drug_pricing (multi-drug comparison), get_enrollment_trends (state enrollment), compare_state_enrollment (multi-state comparison), get_drug_rebate_info (rebate program), search_state_formulary (CA/NY/TX/OH/IL formularies), get_drug_utilization (state prescriptions), get_federal_upper_limits (FUL pricing), list_available_datasets (catalog), search_datasets (custom query)',
                examples: ['get_nadac_pricing', 'search_state_formulary', 'get_drug_rebate_info']
              },
              state: {
                type: 'string',
                description: 'State abbreviation (e.g., "CA", "TX", "NY") - required for get_enrollment_trends',
                examples: ['CA', 'TX', 'NY', 'FL', 'PA']
              },
              states: {
                type: 'array',
                items: { type: 'string' },
                description: 'Array of state abbreviations for compare_state_enrollment',
                examples: [['CA', 'TX', 'NY'], ['FL', 'PA', 'IL']]
              },
              ndc_code: {
                type: 'string',
                description: 'National Drug Code (11-digit) for get_nadac_pricing',
                examples: ['00002-7510-01', '00169-7501-11']
              },
              drug_name: {
                type: 'string',
                description: 'Drug name (partial match supported) for get_nadac_pricing or get_drug_rebate_info',
                examples: ['semaglutide', 'insulin', 'metformin']
              },
              price_date: {
                type: 'string',
                description: 'Specific pricing date (YYYY-MM-DD) for get_nadac_pricing - defaults to latest',
                examples: ['2024-12-11', '2024-01-01']
              },
              start_date: {
                type: 'string',
                description: 'Start date (YYYY-MM-DD) for time-range queries',
                examples: ['2023-01-01', '2024-01-01']
              },
              end_date: {
                type: 'string',
                description: 'End date (YYYY-MM-DD) for time-range queries',
                examples: ['2024-12-01', '2024-12-31']
              },
              enrollment_type: {
                type: 'string',
                enum: ['total', 'medicaid', 'chip', 'adult', 'child'],
                description: 'Type of enrollment data for enrollment methods',
                examples: ['total', 'medicaid', 'chip']
              },
              month: {
                type: 'string',
                description: 'Specific month (YYYY-MM) for compare_state_enrollment',
                examples: ['2024-09', '2024-01']
              },
              ndc_codes: {
                type: 'array',
                items: { type: 'string' },
                description: 'Array of NDC codes for compare_drug_pricing',
                examples: [['00002-7510-01', '00169-7501-11']]
              },
              drug_names: {
                type: 'array',
                items: { type: 'string' },
                description: 'Array of drug names for compare_drug_pricing',
                examples: [['semaglutide', 'dulaglutide']]
              },
              labeler_name: {
                type: 'string',
                description: 'Manufacturer name for get_drug_rebate_info',
                examples: ['Novo Nordisk', 'Pfizer']
              },
              rebate_year: {
                type: 'integer',
                description: 'Year for get_drug_rebate_info',
                examples: [2024, 2023]
              },
              dataset_id: {
                type: 'string',
                description: 'Dataset identifier for search_datasets',
                examples: ['99315a95-37ac-4eee-946a-3c523b4c481e']
              },
              where_clause: {
                type: 'string',
                description: 'SoQL WHERE clause for search_datasets',
                examples: ["state='CA' AND year=2024"]
              },
              limit: {
                type: 'integer',
                description: 'Maximum results to return (default: 100, max: 5000)',
                examples: [100, 500, 1000]
              },
              offset: {
                type: 'integer',
                description: 'Pagination offset (default: 0)',
                examples: [0, 100, 200]
              }
            },
            required: ['method'],
            additionalProperties: false
          }
        }
      ]
    };
  });

• src/medicaid-api.js:62-111 (helper)

  Helper function for NADAC drug pricing lookup, called by 'get_nadac_pricing' method. Downloads/parses CSV data, applies filters, paginates, and formats response.

  async function getNADACPricing(params) {
    const dataset = getDataset('nadac');
    const allData = await getNADACData();
  
    // Filter data based on parameters
    let filtered = allData;
  
    // Filter by NDC code (exact match)
    if (params.ndc_code) {
      const ndc = params.ndc_code.replace(/-/g, ''); // Remove dashes
      filtered = filtered.filter(row => {
        const rowNdc = (row['NDC'] || '').replace(/-/g, '');
        return rowNdc === ndc;
      });
    }
  
    // Filter by drug name (case-insensitive partial match)
    if (params.drug_name) {
      const searchTerm = params.drug_name.toLowerCase();
      filtered = filtered.filter(row => {
        const description = (row['NDC Description'] || '').toLowerCase();
        return description.includes(searchTerm);
      });
    }
  
    // Filter by date
    if (params.price_date) {
      filtered = filtered.filter(row => {
        const effectiveDate = row['Effective Date'] || '';
        return effectiveDate === params.price_date;
      });
    }
  
    // Pagination
    const limit = params.limit || 100;
    const offset = params.offset || 0;
    const paginated = filtered.slice(offset, offset + limit);
  
    // Parse and format
    const parsed = parseNADACData(paginated);
  
    return formatResponse(parsed, {
      dataset: dataset.name,
      total_count: filtered.length,
      returned_count: paginated.length,
      effective_date: params.price_date || 'latest',
      query_type: 'nadac_pricing',
      cache_status: 'loaded from cache'
    });
  }

• src/medicaid-api.js:475-706 (helper)

  Core helper for state formulary search across CA/TX/NY/OH/IL, with state-specific parsing, filtering, NADAC enrichment for CA, and detailed statistics.

  async function searchStateFormulary(params = {}) {
    if (!params.state) {
      throw new Error('state parameter is required (e.g., "CA", "TX", "NY")');
    }
  
    const stateUpper = params.state.toUpperCase();
    const dataset = getFormularyByState(stateUpper);
    const data = await getStateFormularyData(stateUpper);
  
    let results;
  
    // Use state-specific search function based on data structure
    if (stateUpper === 'CA') {
      results = searchFormulary(data, {
        ndc: params.ndc,
        generic_name: params.generic_name,
        label_name: params.label_name,
        requires_pa: params.requires_pa,
        extended_duration: params.extended_duration,
        tier: params.tier,
        limit: params.limit || 100
      });
  
      // AUTO-JOIN NADAC PRICING FOR CALIFORNIA
      // California doesn't publish pricing in formulary, so we enrich with NADAC data
      if (results.length > 0) {
        try {
          // Get NADAC data for all NDCs in results
          const nadacData = await getNADACData();
  
          // Create NADAC lookup map (use most recent record for each NDC)
          const nadacMap = new Map();
          nadacData.forEach(record => {
            const ndc = (record['NDC'] || '').replace(/-/g, '');
            const existing = nadacMap.get(ndc);
            const effectiveDate = record['Effective Date'] || '';
  
            if (!existing || effectiveDate > existing.effective_date) {
              nadacMap.set(ndc, {
                nadac_per_unit: parseFloat(record['NADAC Per Unit']) || null,
                pricing_unit: record['Pricing Unit'] || null,
                effective_date: effectiveDate,
                package_size: record['Package Size'] || null,
                description: record['NDC Description'] || null
              });
            }
          });
  
          // Enrich California results with NADAC pricing
          const caDispensingFee = 10.05; // High volume pharmacy
          results = results.map(product => {
            const ndc = (product.ndc || '').replace(/-/g, '');
            const nadac = nadacMap.get(ndc);
  
            if (nadac && nadac.nadac_per_unit) {
              // Try to determine package size from description
              const description = product.label_name || nadac.description || '';
              let packageSize = 1.0; // Default
  
              // Parse package size from description (e.g., "1.5 ML", "3 ML")
              const mlMatch = description.match(/([\d.]+)\s*ML/i);
              if (mlMatch) {
                packageSize = parseFloat(mlMatch[1]);
              }
  
              // Calculate California Medicaid reimbursement
              const estimatedReimbursement = (nadac.nadac_per_unit * packageSize) + caDispensingFee;
  
              return {
                ...product,
                // NADAC pricing fields
                nadac_per_unit: nadac.nadac_per_unit,
                nadac_pricing_unit: nadac.pricing_unit,
                nadac_effective_date: nadac.effective_date,
                nadac_package_size: packageSize,
                // California Medicaid calculated pricing
                ca_estimated_reimbursement: parseFloat(estimatedReimbursement.toFixed(2)),
                ca_dispensing_fee: caDispensingFee,
                pricing_notes: 'CA reimbursement = (NADAC per unit × package size) + dispensing fee'
              };
            }
  
            return product; // No NADAC data available for this NDC
          });
        } catch (error) {
          console.warn('[NADAC Integration] Failed to enrich CA formulary with pricing:', error.message);
          // Continue without pricing data rather than failing the entire request
        }
      }
  
    } else if (stateUpper === 'TX') {
      results = searchTexasFormulary(data, {
        ndc: params.ndc,
        generic_name: params.generic_name,
        label_name: params.label_name,
        requires_pa: params.requires_pa,
        pdl_pa: params.pdl_pa,
        clinical_pa: params.clinical_pa,
        program: params.program,
        max_price: params.max_price,
        min_price: params.min_price,
        limit: params.limit || 100
      });
    } else if (stateUpper === 'NY') {
      // New York formulary search
      results = searchNewYorkFormulary(data, {
        ndc: params.ndc,
        generic_name: params.generic_name,
        label_name: params.label_name,
        requires_pa: params.requires_pa,
        preferred: params.preferred,
        is_brand: params.is_brand,
        max_price: params.max_price,
        min_price: params.min_price,
        limit: params.limit || 100
      });
    } else if (stateUpper === 'OH') {
      // Ohio formulary search
      results = searchOhioFormulary(data, {
        ndc: params.ndc,
        generic_name: params.generic_name,
        label_name: params.label_name,
        requires_pa: params.requires_pa,
        step_therapy: params.step_therapy,
        has_quantity_limit: params.has_quantity_limit,
        is_brand: params.is_brand,
        otc: params.otc,
        limit: params.limit || 100
      });
    } else if (stateUpper === 'IL') {
      // Illinois formulary search (enriched with CA/NY NDC codes)
      results = searchIllinoisFormulary(data, {
        ndc: params.ndc,
        generic_name: params.generic_name,
        label_name: params.label_name,
        requires_pa: params.requires_pa,
        match_confidence: params.match_confidence,
        has_ndc: params.has_ndc,
        limit: params.limit || 100
      });
    } else {
      throw new Error(`Search not implemented for state: ${stateUpper}`);
    }
  
    // Calculate state-specific statistics
    let stats = {
      total_records: data.length,
      matching_records: results.length,
      unique_generic_drugs: new Set(results.map(r => r.generic_name)).size,
      pa_required_count: results.filter(r => r.prior_authorization).length
    };
  
    // Add CA-specific stats
    if (stateUpper === 'CA') {
      stats.extended_duration_count = results.filter(r => r.extended_duration_drug).length;
      stats.brand_count = results.filter(r => r.cost_ceiling_tier === 'Brand').length;
      stats.generic_count = results.filter(r => r.cost_ceiling_tier === 'Generic').length;
      stats.with_pricing_count = results.filter(r => r.nadac_per_unit !== undefined).length;
  
      // Calculate average pricing for products with NADAC data
      const productsWithPricing = results.filter(r => r.ca_estimated_reimbursement !== undefined);
      if (productsWithPricing.length > 0) {
        stats.avg_ca_reimbursement = (
          productsWithPricing.reduce((sum, r) => sum + r.ca_estimated_reimbursement, 0) /
          productsWithPricing.length
        ).toFixed(2);
        stats.avg_nadac_per_unit = (
          productsWithPricing.reduce((sum, r) => sum + r.nadac_per_unit, 0) /
          productsWithPricing.length
        ).toFixed(2);
      }
    }
  
    // Add TX-specific stats
    if (stateUpper === 'TX') {
      stats.medicaid_active_count = results.filter(r => r.medicaid_active).length;
      stats.chip_active_count = results.filter(r => r.chip_active).length;
      stats.pdl_pa_required_count = results.filter(r => r.pdl_pa_required).length;
      stats.clinical_pa_required_count = results.filter(r => r.clinical_pa_required).length;
      stats.avg_retail_price = results.filter(r => r.retail_price !== null).length > 0
        ? (results.filter(r => r.retail_price !== null).reduce((sum, r) => sum + r.retail_price, 0) /
           results.filter(r => r.retail_price !== null).length).toFixed(2)
        : null;
    }
  
    // Add NY-specific stats
    if (stateUpper === 'NY') {
      stats.brand_count = results.filter(r => r.is_brand).length;
      stats.generic_count = results.filter(r => r.is_generic).length;
      stats.preferred_count = results.filter(r => r.preferred_drug).length;
      stats.with_pricing_count = results.filter(r => r.mra_cost !== null).length;
  
      // Calculate average MRA pricing
      const productsWithPricing = results.filter(r => r.mra_cost !== null);
      if (productsWithPricing.length > 0) {
        stats.avg_mra_cost = (
          productsWithPricing.reduce((sum, r) => sum + r.mra_cost, 0) /
          productsWithPricing.length
        ).toFixed(2);
      }
    }
  
    // Add OH-specific stats
    if (stateUpper === 'OH') {
      stats.brand_count = results.filter(r => r.is_brand).length;
      stats.generic_count = results.filter(r => r.is_generic).length;
      stats.step_therapy_count = results.filter(r => r.step_therapy !== null).length;
      stats.quantity_limit_count = results.filter(r => r.quantity_limit !== null).length;
      stats.otc_count = results.filter(r => r.is_otc).length;
    }
  
    // Add IL-specific stats (cross-state enrichment metrics)
    if (stateUpper === 'IL') {
      stats.with_ndc_count = results.filter(r => r.ndc !== null).length;
      stats.without_ndc_count = results.filter(r => r.ndc === null).length;
      stats.enrichment_rate = ((stats.with_ndc_count / results.length) * 100).toFixed(1) + '%';
      stats.ca_source_count = results.filter(r => r.ndc_source === 'CA').length;
      stats.ny_source_count = results.filter(r => r.ndc_source === 'NY').length;
      stats.oh_source_count = results.filter(r => r.ndc_source === 'OH').length;
      stats.high_confidence_count = results.filter(r => r.match_confidence === 'high').length;
      stats.medium_confidence_count = results.filter(r => r.match_confidence === 'medium').length;
    }
  
    return {
      state: stateUpper,
      state_name: stateUpper === 'CA' ? 'California' : stateUpper === 'TX' ? 'Texas' : stateUpper === 'NY' ? 'New York' : stateUpper === 'OH' ? 'Ohio' : stateUpper === 'IL' ? 'Illinois' : stateUpper,
      dataset: dataset.name,
      query_params: params,
      statistics: stats,
      results: results
    };
  }