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 }; }