mcp

MCP Server Reference

Last updated: Jan 20, 2025

Complete documentation for the @findicd10/mcp Model Context Protocol server.

Installation

bash

# Run directly with npx (recommended)
npx @findicd10/mcp

# Or install globally
npm install -g @findicd10/mcp
findicd10-mcp

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "findicd10": {
      "command": "npx",
      "args": ["-y", "@findicd10/mcp"]
    }
  }
}

Environment Variables

Variable	Default	Description
`FINDICD10_API_BASE`	`https://findicd10.com/api`	API base URL (for self-hosted instances)

Tools

The MCP server exposes 5 tools for ICD-10 code operations.

search_codes

Search across all ICD-10-CM diagnosis codes using full-text search.

Schema

typescript

{
  query: string,           // Search query (required)
  version?: "2025" | "2026",  // ICD-10 version (default: "2026")
  billable_only?: boolean, // Only billable codes (default: false)
  limit?: number           // Max results 1-100 (default: 50)
}

Example

Input:

json

{
  "query": "type 2 diabetes hyperglycemia",
  "billable_only": true,
  "limit": 5
}

Output:

json

{
  "results": [
    {
      "code": "E11.65",
      "name": "Type 2 diabetes mellitus with hyperglycemia",
      "description": "Type 2 diabetes mellitus with hyperglycemia",
      "is_billable": true,
      "path": "/E00-E89/E08-E13/E11/E11.6/E11.65"
    },
    {
      "code": "E11.69",
      "name": "Type 2 diabetes mellitus with other specified complication",
      "description": "Type 2 diabetes mellitus with other specified complication",
      "is_billable": true,
      "path": "/E00-E89/E08-E13/E11/E11.6/E11.69"
    }
  ],
  "count": 2,
  "query": "type 2 diabetes hyperglycemia"
}

get_code

Get detailed information about a specific ICD-10-CM code including clinical notes, excludes, and hierarchy.

Schema

typescript

{
  code: string  // ICD-10-CM code (required, e.g., "E11.65")
}

Example

Input:

json

{
  "code": "E11.65"
}

Output:

json

{
  "code": "E11.65",
  "description": "Type 2 diabetes mellitus with hyperglycemia",
  "isBillable": true,
  "type": "CODE",
  "details": {
    "notes": [],
    "codeFirst": [],
    "codeAlso": [],
    "useAdditionalCode": [
      "Use additional code to identify control using:",
      "insulin (Z79.4)",
      "oral antidiabetic drugs (Z79.84)"
    ],
    "excludes1": [
      "diabetes mellitus due to underlying condition (E08.-)",
      "drug or chemical induced diabetes mellitus (E09.-)",
      "gestational diabetes (O24.4-)",
      "type 1 diabetes mellitus (E10.-)"
    ],
    "excludes2": [],
    "inclusionTerms": [],
    "sevenCharNote": null,
    "sevenCharDefs": []
  },
  "children": [],
  "path": "/E00-E89/E08-E13/E11/E11.6/E11.65"
}

Clinical Notes Fields

Field	Description
`notes`	General clinical guidance
`codeFirst`	Code another condition before this one
`codeAlso`	Consider coding additional conditions
`useAdditionalCode`	Add codes for more specificity
`excludes1`	Codes that CANNOT be used together (mutually exclusive)
`excludes2`	"Not included here" but CAN be coded together
`inclusionTerms`	Alternative names/conditions included
`sevenCharNote`	Instructions for 7th character extensions
`sevenCharDefs`	7th character definitions (A=initial, D=subsequent, S=sequela)

get_related_codes

Find parent and sibling codes in the ICD-10 hierarchy for context and code selection.

Schema

typescript

{
  code: string  // ICD-10-CM code (required)
}

Example

Input:

json

{
  "code": "E11.65"
}

Output:

json

{
  "code": "E11.65",
  "siblings": [
    {
      "code": "E11.61",
      "name": "Type 2 diabetes mellitus with diabetic arthropathy",
      "is_billable": false,
      "node_type": "category"
    },
    {
      "code": "E11.62",
      "name": "Type 2 diabetes mellitus with skin complications",
      "is_billable": false,
      "node_type": "category"
    },
    {
      "code": "E11.63",
      "name": "Type 2 diabetes mellitus with oral complications",
      "is_billable": false,
      "node_type": "category"
    },
    {
      "code": "E11.64",
      "name": "Type 2 diabetes mellitus with hypoglycemia",
      "is_billable": false,
      "node_type": "category"
    },
    {
      "code": "E11.65",
      "name": "Type 2 diabetes mellitus with hyperglycemia",
      "is_billable": true,
      "node_type": "code"
    },
    {
      "code": "E11.69",
      "name": "Type 2 diabetes mellitus with other specified complication",
      "is_billable": true,
      "node_type": "code"
    }
  ]
}

convert_code

Convert between ICD-9-CM and ICD-10-CM codes using official CMS GEM (General Equivalence Mappings).

Schema

typescript

{
  code: string,              // ICD-9 or ICD-10 code (required)
  version?: "2025" | "2026"  // ICD-10 version (default: "2026")
}

The tool automatically detects whether you're providing an ICD-9 or ICD-10 code:
- ICD-9 codes start with: 0-9, V, or E
- ICD-10 codes start with: A-T or Z

Example: ICD-9 to ICD-10

Input:

json

{
  "code": "250.00"
}

Output:

json

{
  "inputCode": "250.00",
  "inputType": "icd9",
  "mappings": [
    {
      "icd9_code": "25000",
      "icd10_code": "E119",
      "direction": "forward",
      "approximate": true,
      "no_map": false,
      "combination": false
    }
  ],
  "note": "ICD-10 code E119 = E11.9 (Type 2 diabetes mellitus without complications)"
}

Example: ICD-10 to ICD-9

Input:

json

{
  "code": "E11.65"
}

Output:

json

{
  "inputCode": "E11.65",
  "inputType": "icd10",
  "mappings": [
    {
      "icd9_code": "25002",
      "icd10_code": "E1165",
      "direction": "backward",
      "approximate": true,
      "no_map": false,
      "combination": false
    }
  ],
  "note": "ICD-9 code 25002 = 250.02 (Diabetes mellitus type II, uncontrolled)"
}

Mapping Flags

Flag	Description
`approximate`	The mapping is not exact; clinical judgment required
`no_map`	No equivalent code exists in the target system
`combination`	Multiple codes may be needed for complete mapping

analyze_note

Extract ICD-10 codes from clinical text using AI analysis. Useful for coding assistance and documentation review.

Schema

typescript

{
  note: string  // Clinical note text (required)
}

Example

Input:

json

{
  "note": "45-year-old male presents with chest pain, shortness of breath, and history of COPD. ECG shows atrial fibrillation. Started on anticoagulation."
}

Output:

json

{
  "codes": [
    {
      "Code": "R07.9",
      "Rationale": "Chief complaint of chest pain documented",
      "Confidence": 5,
      "Description": "Chest pain, unspecified",
      "Billable": true
    },
    {
      "Code": "R06.02",
      "Rationale": "Shortness of breath symptom documented",
      "Confidence": 5,
      "Description": "Shortness of breath",
      "Billable": true
    },
    {
      "Code": "J44.9",
      "Rationale": "History of COPD documented without exacerbation specified",
      "Confidence": 4,
      "Description": "Chronic obstructive pulmonary disease, unspecified",
      "Billable": true
    },
    {
      "Code": "I48.91",
      "Rationale": "Atrial fibrillation diagnosed on ECG",
      "Confidence": 5,
      "Description": "Unspecified atrial fibrillation",
      "Billable": true
    },
    {
      "Code": "Z79.01",
      "Rationale": "Patient started on anticoagulation therapy",
      "Confidence": 4,
      "Description": "Long term (current) use of anticoagulants",
      "Billable": true
    }
  ],
  "note_length": 156,
  "analysis_model": "gemini-2.0-flash"
}

Confidence Levels

Level	Meaning
5	High confidence - explicitly documented
4	Good confidence - strongly implied
3	Moderate confidence - reasonably inferred
2	Low confidence - possibly relevant
1	Very low confidence - may need clarification

Best Practices

Provide complete context - Include relevant history, findings, and assessments
Review AI suggestions - Always verify codes against documentation
Check specificity - The AI may suggest general codes when specific ones apply
Consider excludes - Check excludes notes before final code selection

Error Handling

The MCP server returns structured errors:

json

{
  "error": {
    "code": "INVALID_CODE",
    "message": "Code 'XYZ123' not found in ICD-10-CM database"
  }
}

Error Codes

Code	Description
`INVALID_CODE`	The specified code doesn't exist
`INVALID_QUERY`	Search query is empty or invalid
`RATE_LIMITED`	Too many requests (wait and retry)
`API_ERROR`	Upstream API error (try again)
`INVALID_VERSION`	Unsupported ICD-10 version

Supported Versions

Version	Status	Codes
2026	Current (default)	47,192
2025	Supported	46,808

Package

npm: @findicd10/mcp

Support

Documentation: findicd10.com/developers
Contact: findicd10.com/contact