Skip to main content

MCP Tools

Complete catalog of Model Context Protocol (MCP) tools available in Patient Journey Intelligence for clinical NLP, terminology services, patient data access, and healthcare workflows.

Pre-Built Healthcare AI Tools

70+ production-ready MCP tools for clinical entity extraction, medical terminology lookup, patient cohort building, quality measurement, and more.

Tool Categories​

🔍

Clinical NLP Tools

Extract entities, relationships, and assertions from clinical text

9 tools including NER, RE, de-identification

📚

Terminology Tools

Search and map medical codes across standard vocabularies

12 tools covering SNOMED, RxNorm, LOINC, ICD

👤

Patient Data Tools

Query OMOP CDM for patient demographics, conditions, meds

8 tools for OMOP table access

🧬

Cohort Building Tools

Define patient populations using clinical criteria

5 tools for inclusion/exclusion logic

📊

Clinical Measures Tools

Calculate quality metrics and performance indicators

7 tools for HEDIS, CMS, custom measures

🔒

De-Identification Tools

Detect and redact PHI for research and sharing

4 tools for HIPAA Safe Harbor compliance

Clinical NLP Tools​

extract_clinical_entities​

Extract named entities from clinical text (diagnoses, medications, procedures, anatomy, tests).

Input Schema:

{
  "text": "string (required) - Clinical note or report text",
  "entity_types": "array (optional) - Specific types to extract: PROBLEM, DRUG, PROCEDURE, ANATOMY, TEST, etc.",
  "return_offsets": "boolean (optional) - Include character offsets for each entity",
  "confidence_threshold": "number (optional) - Minimum confidence score (0.0-1.0)"
}

Example Request:

{
  "text": "Patient presents with acute MI. Started on aspirin 81mg, atorvastatin 40mg, and metoprolol 25mg BID.",
  "entity_types": ["PROBLEM", "DRUG"],
  "confidence_threshold": 0.8
}

Example Response:

{
  "entities": [
    {
      "text": "acute MI",
      "type": "PROBLEM",
      "confidence": 0.95,
      "begin": 22,
      "end": 30,
      "normalized": "Acute myocardial infarction"
    },
    {
      "text": "aspirin",
      "type": "DRUG",
      "confidence": 0.98,
      "begin": 43,
      "end": 50,
      "normalized": "Aspirin"
    },
    {
      "text": "atorvastatin",
      "type": "DRUG",
      "confidence": 0.97,
      "begin": 57,
      "end": 69
    },
    {
      "text": "metoprolol",
      "type": "DRUG",
      "confidence": 0.96,
      "begin": 79,
      "end": 89
    }
  ]
}

extract_relations​

Identify relationships between clinical entities (drug-dosage, problem-treatment, test-result).

Input Schema:

{
  "text": "string (required) - Clinical text",
  "relation_types": "array (optional) - DRUG_DOSAGE, PROBLEM_TREATMENT, TEST_RESULT, etc.",
  "entities": "array (optional) - Pre-extracted entities to use as anchors"
}

Example:

Input: {
  "text": "Started metformin 500mg BID for Type 2 Diabetes",
  "relation_types": ["DRUG_DOSAGE", "DRUG_REASON"]
}

Output: {
  "relations": [
    {
      "type": "DRUG_DOSAGE",
      "entity1": "metformin",
      "entity2": "500mg BID",
      "confidence": 0.94
    },
    {
      "type": "DRUG_REASON",
      "entity1": "metformin",
      "entity2": "Type 2 Diabetes",
      "confidence": 0.92
    }
  ]
}

detect_assertion_status​

Determine assertion status: present, absent, possible, hypothetical, historical.

Example:

Input: {
  "text": "No evidence of pneumonia. Patient denies chest pain. Family history of diabetes."
}

Output: {
  "assertions": [
    {"entity": "pneumonia", "status": "absent", "confidence": 0.98},
    {"entity": "chest pain", "status": "absent", "confidence": 0.96},
    {"entity": "diabetes", "status": "family_history", "confidence": 0.94}
  ]
}

extract_temporal_info​

Extract dates, durations, and temporal relationships from clinical text.

Example:

Input: {
  "text": "Patient diagnosed 3 months ago. Started treatment on 2024-01-15. Follow-up in 6 weeks."
}

Output: {
  "temporal_expressions": [
    {"text": "3 months ago", "type": "relative_date", "normalized": "2023-10-07"},
    {"text": "2024-01-15", "type": "absolute_date", "normalized": "2024-01-15"},
    {"text": "6 weeks", "type": "duration", "normalized": "P6W"}
  ]
}

de_identify_text​

Remove or mask PHI according to HIPAA Safe Harbor guidelines.

Input Schema:

{
  "text": "string (required) - Text to de-identify",
  "strategy": "string (optional) - 'redact', 'mask', 'replace', 'shift_dates'",
  "entity_types": "array (optional) - Specific PHI types to remove"
}

Example:

Input: {
  "text": "Patient John Smith, DOB 05/15/1975, MRN 12345, seen on 2024-01-15",
  "strategy": "mask"
}

Output: {
  "de_identified_text": "Patient [NAME], DOB [DATE], MRN [ID], seen on [DATE]",
  "phi_found": [
    {"type": "PATIENT_NAME", "text": "John Smith", "begin": 8, "end": 18},
    {"type": "DATE", "text": "05/15/1975", "begin": 24, "end": 34},
    {"type": "ID", "text": "12345", "begin": 40, "end": 45},
    {"type": "DATE", "text": "2024-01-15", "begin": 55, "end": 65}
  ]
}

Terminology Tools​

search_terminology​

Search medical terminology systems for codes and descriptions.

Input Schema:

{
  "query": "string (required) - Search term",
  "terminology": "string (required) - SNOMED_CT, RXNORM, LOINC, ICD10CM, CPT, etc.",
  "limit": "number (optional) - Max results (default 10)",
  "semantic_type": "string (optional) - Filter by UMLS semantic type"
}

Example:

Input: {
  "query": "diabetes mellitus type 2",
  "terminology": "SNOMED_CT",
  "limit": 3
}

Output: {
  "results": [
    {
      "code": "44054006",
      "display": "Type 2 diabetes mellitus",
      "system": "http://snomed.info/sct",
      "score": 0.98
    },
    {
      "code": "59079001",
      "display": "Type 2 diabetes mellitus without complication",
      "system": "http://snomed.info/sct",
      "score": 0.92
    },
    {
      "code": "368401007",
      "display": "Type 2 diabetes mellitus with complication",
      "system": "http://snomed.info/sct",
      "score": 0.87
    }
  ]
}

map_codes​

Map codes between different terminology systems.

Example:

Input: {
  "source_code": "44054006",
  "source_system": "SNOMED_CT",
  "target_system": "ICD10CM"
}

Output: {
  "mappings": [
    {
      "target_code": "E11.9",
      "target_display": "Type 2 diabetes mellitus without complications",
      "equivalence": "equivalent"
    }
  ]
}

check_drug_interactions​

Identify potential adverse drug-drug interactions.

Input Schema:

{
  "medications": "array (required) - List of drug names or RxNorm codes",
  "severity_filter": "string (optional) - 'major', 'moderate', 'minor'"
}

Example:

Input: {
  "medications": ["warfarin", "aspirin", "ibuprofen"],
  "severity_filter": "major"
}

Output: {
  "interactions": [
    {
      "drug1": "warfarin",
      "drug2": "ibuprofen",
      "severity": "major",
      "description": "NSAIDs increase anticoagulant effect, raising bleeding risk",
      "mechanism": "Platelet inhibition + anticoagulation",
      "recommendation": "Avoid concurrent use. Consider acetaminophen alternative."
    },
    {
      "drug1": "warfarin",
      "drug2": "aspirin",
      "severity": "major",
      "description": "Dual antiplatelet/anticoagulation increases bleeding risk",
      "recommendation": "Use only if clinically necessary with close INR monitoring"
    }
  ]
}

lookup_lab_reference_ranges​

Get normal reference ranges for lab tests by LOINC code.

Example:

Input: {
  "loinc_code": "2345-7", // Glucose
  "age": 45,
  "sex": "M"
}

Output: {
  "test_name": "Glucose [Mass/volume] in Serum or Plasma",
  "reference_range": {
    "low": 70,
    "high": 100,
    "unit": "mg/dL",
    "age_group": "adult",
    "sex": "M"
  },
  "critical_low": 40,
  "critical_high": 400
}

Patient Data Tools​

query_patient_data​

Query OMOP CDM for patient clinical data.

Input Schema:

{
  "patient_id": "string (required) - Patient identifier",
  "tables": "array (required) - OMOP tables: condition, drug_exposure, procedure, measurement, etc.",
  "date_range": "object (optional) - {start: 'YYYY-MM-DD', end: 'YYYY-MM-DD'}",
  "filters": "object (optional) - Additional filtering criteria"
}

Example:

Input: {
  "patient_id": "patient_12345",
  "tables": ["condition_occurrence", "drug_exposure"],
  "date_range": {"start": "2023-01-01", "end": "2023-12-31"}
}

Output: {
  "patient_id": "patient_12345",
  "conditions": [
    {
      "condition_concept_name": "Type 2 diabetes mellitus",
      "condition_start_date": "2023-03-15",
      "condition_type": "EHR diagnosis"
    },
    {
      "condition_concept_name": "Hypertension",
      "condition_start_date": "2023-03-15",
      "condition_type": "EHR diagnosis"
    }
  ],
  "medications": [
    {
      "drug_concept_name": "Metformin 500 MG Oral Tablet",
      "drug_exposure_start_date": "2023-03-20",
      "quantity": 60,
      "days_supply": 30
    }
  ]
}

get_patient_timeline​

Get chronological timeline of all clinical events for a patient.

Example:

Input: {
  "patient_id": "patient_12345",
  "date_range": {"start": "2023-01-01", "end": "2023-12-31"}
}

Output: {
  "timeline": [
    {
      "date": "2023-03-15",
      "events": [
        {"type": "visit", "description": "Outpatient visit"},
        {"type": "condition", "description": "Diagnosed with Type 2 Diabetes"},
        {"type": "condition", "description": "Diagnosed with Hypertension"}
      ]
    },
    {
      "date": "2023-03-20",
      "events": [
        {"type": "medication", "description": "Started Metformin 500mg BID"},
        {"type": "medication", "description": "Started Lisinopril 10mg daily"}
      ]
    }
  ]
}

Cohort Building Tools​

build_cohort​

Define patient cohorts using inclusion/exclusion criteria.

Input Schema:

{
  "name": "string (required) - Cohort name",
  "inclusion_criteria": "array (required) - List of criteria that must be met",
  "exclusion_criteria": "array (optional) - List of criteria that disqualify patients",
  "date_range": "object (optional) - Observation period"
}

Example:

Input: {
  "name": "Uncontrolled T2DM on Metformin",
  "inclusion_criteria": [
    {
      "type": "condition",
      "concept": "Type 2 diabetes mellitus",
      "date_range": {"start": "2020-01-01", "end": "2024-01-01"}
    },
    {
      "type": "drug",
      "concept": "Metformin",
      "status": "active"
    },
    {
      "type": "measurement",
      "concept": "Hemoglobin A1c",
      "operator": ">",
      "value": 8.0,
      "date_range": {"start": "2024-01-01", "end": "2024-04-01"}
    }
  ],
  "exclusion_criteria": [
    {
      "type": "condition",
      "concept": "Type 1 diabetes mellitus"
    }
  ]
}

Output: {
  "cohort_id": "cohort_67890",
  "name": "Uncontrolled T2DM on Metformin",
  "patient_count": 247,
  "created_at": "2024-01-15T10:30:00Z"
}

export_cohort​

Export cohort patient list or clinical data.

Example:

Input: {
  "cohort_id": "cohort_67890",
  "format": "csv",
  "include_data": ["demographics", "conditions", "medications"],
  "de_identify": true
}

Output: {
  "download_url": "https://platform.ai/exports/cohort_67890.csv",
  "expires_at": "2024-01-16T10:30:00Z",
  "record_count": 247
}

Clinical Measures Tools​

calculate_quality_measure​

Calculate HEDIS, CMS, or custom quality measures.

Input Schema:

{
  "measure_id": "string (required) - Measure identifier (e.g., 'CDC-HbA1c-Control')",
  "cohort_id": "string (optional) - Pre-defined cohort, or",
  "patient_ids": "array (optional) - Specific patients",
  "measurement_period": "object (required) - {start: 'YYYY-MM-DD', end: 'YYYY-MM-DD'}"
}

Example:

Input: {
  "measure_id": "CDC-HbA1c-Control",
  "cohort_id": "cohort_67890",
  "measurement_period": {"start": "2023-01-01", "end": "2023-12-31"}
}

Output: {
  "measure_name": "Comprehensive Diabetes Care: HbA1c Control (<8%)",
  "numerator": 189,
  "denominator": 247,
  "performance_rate": 76.5,
  "benchmark": 70.0,
  "meets_benchmark": true,
  "stratifications": [
    {"group": "Age 18-64", "rate": 78.2},
    {"group": "Age 65+", "rate": 73.1}
  ]
}

Error Handling​

All MCP tools return errors in a standardized format:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Missing required parameter 'patient_id'",
    "details": {
      "parameter": "patient_id",
      "expected_type": "string"
    }
  }
}

Common Error Codes:

  • INVALID_INPUT - Missing or malformed parameters
  • NOT_FOUND - Resource doesn't exist (patient, cohort, etc.)
  • UNAUTHORIZED - Invalid API key or insufficient permissions
  • RATE_LIMIT_EXCEEDED - Too many requests
  • INTERNAL_ERROR - Server-side processing error

Rate Limits & Quotas​

📊 API Usage Limits

  • Standard Tier: 1,000 tool calls per hour, 10,000 per day
  • Professional Tier: 10,000 tool calls per hour, 100,000 per day
  • Enterprise Tier: Custom limits based on SLA

Rate limit headers included in every response:

  • X-RateLimit-Limit: Maximum requests per hour
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Timestamp when limit resets

Tool Discovery​

Use the list_tools MCP method to dynamically discover all available tools and their schemas:

// Request
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

// Response
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "extract_clinical_entities",
        "description": "Extract named entities from clinical text",
        "inputSchema": {
          "type": "object",
          "properties": {
            "text": {"type": "string"},
            "entity_types": {"type": "array", "items": {"type": "string"}}
          },
          "required": ["text"]
        }
      },
      // ... more tools
    ]
  }
}

Best Practices​

💡 Tool Usage Tips

  • Batch similar operations: Use single queries with multiple patients instead of per-patient queries
  • Set confidence thresholds: For NLP extraction, filter low-confidence results to reduce false positives
  • Use specific entity types: Requesting all entity types is slower than specifying only what you need
  • Cache terminology lookups: Medical codes are stable – cache search results to reduce API calls
  • Handle pagination: Large result sets are paginated – use offset and limit parameters
  • Validate inputs: Check required parameters before calling tools to avoid unnecessary errors

Next Steps​

MCP Agents SetupMedical LLM & VLMPlatform REST APIBuilding Agents Overview
Last updated on