Medicaid MCP Server

Instructions

Implementation Reference

• src/index.js:33-152 (registration)

  Registers the 'medicaid_info' tool in the ListToolsRequestSchema response, including name, description, and complete input schema definition.
  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', 'list_available_datasets', 'search_datasets' ], description: 'The operation to perform: get_nadac_pricing (NADAC drug pricing lookup), compare_drug_pricing (multi-drug or temporal comparison), get_enrollment_trends (state monthly enrollment), compare_state_enrollment (multi-state comparison), get_drug_rebate_info (rebate program data), list_available_datasets (dataset catalog), search_datasets (custom SoQL query)', examples: ['get_nadac_pricing', 'get_enrollment_trends', 'compare_state_enrollment'] }, 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:39-148 (schema)

  Detailed input schema for medicaid_info tool defining all parameters including method (required), state, ndc_code, drug_name, dates, limits, etc., with types, enums, descriptions, and examples.
  inputSchema: { type: 'object', properties: { method: { type: 'string', enum: [ 'get_nadac_pricing', 'compare_drug_pricing', 'get_enrollment_trends', 'compare_state_enrollment', 'get_drug_rebate_info', 'list_available_datasets', 'search_datasets' ], description: 'The operation to perform: get_nadac_pricing (NADAC drug pricing lookup), compare_drug_pricing (multi-drug or temporal comparison), get_enrollment_trends (state monthly enrollment), compare_state_enrollment (multi-state comparison), get_drug_rebate_info (rebate program data), list_available_datasets (dataset catalog), search_datasets (custom SoQL query)', examples: ['get_nadac_pricing', 'get_enrollment_trends', 'compare_state_enrollment'] }, 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:155-224 (handler)

  Executes the medicaid_info tool: validates name, extracts method and params, dispatches to specific helper functions via switch, returns JSON result or error.
  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 '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/medicaid-api.js:56-105 (helper)

  Core helper function for 'get_nadac_pricing' method: loads cached NADAC dataset, filters by NDC code, drug name, date; applies pagination, parsing, and formatting.
  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:178-236 (helper)

  Core helper for 'get_enrollment_trends': loads enrollment data, filters by state and date range, sorts chronologically, paginates, parses and formats response.
  async function getEnrollmentTrends(params) { const dataset = getDataset('enrollment'); const allData = await getEnrollmentData(); let filtered = allData; // Filter by state if (params.state) { const stateUpper = params.state.toUpperCase(); filtered = filtered.filter(row => { const state = (row['State Abbreviation'] || '').toUpperCase(); return state === stateUpper; }); } // Filter by date range (using Reporting Period YYYYMM format) if (params.start_date && params.end_date) { // Convert YYYY-MM-DD to YYYYMM for comparison const startPeriod = params.start_date.replace(/-/g, '').substring(0, 6); const endPeriod = params.end_date.replace(/-/g, '').substring(0, 6); filtered = filtered.filter(row => { const reportPeriod = row['Reporting Period'] || ''; return reportPeriod >= startPeriod && reportPeriod <= endPeriod; }); } // Filter by enrollment type if (params.enrollment_type) { // This depends on the actual column names in the enrollment CSV // Will need to map enrollment_type to actual columns } // Sort by date (Reporting Period YYYYMM format) filtered.sort((a, b) => { const periodA = a['Reporting Period'] || ''; const periodB = b['Reporting Period'] || ''; return periodA.localeCompare(periodB); // Ascending for trends }); // Pagination const limit = params.limit || 100; const offset = params.offset || 0; const paginated = filtered.slice(offset, offset + limit); const parsed = parseEnrollmentData(paginated); return formatResponse(parsed, { dataset: dataset.name, total_count: filtered.length, returned_count: paginated.length, state: params.state || 'all', date_range: { start: params.start_date, end: params.end_date }, query_type: 'enrollment_trends' }); }