Healthcare Eligibility Check MCP Server

A Model Context Protocol (MCP) server that enables Claude to perform healthcare insurance eligibility checks by integrating with patient APIs (via OAuth), NPI provider lookups, and Stedi X12 270/271 eligibility verification.

Features

• Patient Search: OAuth-authenticated search for patient records by name, DOB, or patient ID
• NPI Provider Lookup: Search providers using the NPI Registry API
• Eligibility Verification: Submit X12 270 eligibility requests via Stedi and parse 271 responses
• Secure Authentication: OAuth 2.0 authorization code flow with refresh token caching

Prerequisites

• Node.js 18+ or compatible runtime
• Patient API credentials (OAuth client ID and secret)
• Stedi API key and partner ID
• Access to NPI Registry API (public)
• Claude Pro, Team, or Enterprise subscription (for Claude Desktop MCP integration)
  • Free Claude accounts do not support MCP servers
  • See alternatives below if you have a free account

Installation

1. Install dependencies:

npm install

2. Copy .env.example to .env and configure:

cp .env.example .env

3. Edit .env with your credentials:

PATIENT_API_BASE_URL=https://your-patient-api.com
PATIENT_API_CLIENT_ID=your_client_id
PATIENT_API_CLIENT_SECRET=your_secret
PATIENT_API_TOKEN_URL=https://auth.your-api.com/oauth/token
PATIENT_API_SCOPE=patient:read
PATIENT_API_ACCESS_TOKEN=your_access_token
PATIENT_API_REFRESH_TOKEN=your_refresh_token

STEDI_API_KEY=your_stedi_api_key
STEDI_API_URL=https://healthcare.us.stedi.com/2024-04-01
STEDI_PARTNER_ID=your_partner_id

Note: To obtain access and refresh tokens, you'll need to complete an OAuth authorization flow through your Patient API provider's authorization endpoint.

Development

Build the project:

npm run build

Run in development mode with auto-reload:

npm run dev

Run the built server:

npm start

MCP Tools Available

1. search_patient

Search for patients using OAuth-authenticated API.

Parameters:

• searchType: "name", "dob", or "patientId"
• firstName: Patient's first name (for name search)
• lastName: Patient's last name (for name search)
• dateOfBirth: Date of birth in YYYY-MM-DD format
• patientId: Unique patient identifier

2. lookup_npi

Lookup healthcare providers in the NPI Registry.

Parameters:

• searchType: "name", "npi", or "taxonomy"
• firstName: Provider's first name
• lastName: Provider's last name
• npiNumber: 10-digit NPI number
• taxonomy: Taxonomy code
• state: State abbreviation to filter results

3. check_eligibility

Submit insurance eligibility check to Stedi API.

Parameters:

• patientInfo: Object with memberId, firstName, lastName, dateOfBirth
• providerInfo: Object with npi, optional firstName/lastName
• payerId: Payer ID (optional) - Common payers:
  • 62308 - Cigna
  • 68069 - Ambetter
  • 60054 - Aetna
  • If not specified, uses STEDI_PARTNER_ID from environment
• serviceType: Service type code (default: "30" for health benefit plan coverage)

4. get_oauth_token

Manually get or refresh OAuth token (typically called automatically).

Parameters:

• forceRefresh: Boolean to force token refresh

VS Code MCP Configuration

To use this server with Claude in VS Code, add to .vscode/mcp.json:

{
  "servers": {
    "healthcare-eligibility": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}

Or for development with tsx:

{
  "servers": {
    "healthcare-eligibility": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "src/index.ts"]
    }
  }
}

Usage Example

Once configured, Claude can use these tools naturally:

User: "Check eligibility for patient John Doe, DOB 1990-01-15, with Dr. Smith using Cigna"

Claude will:
1. Search for patient "John Doe" with DOB 1990-01-15
2. Lookup Dr. Smith in NPI registry
3. Submit eligibility check with patient, provider info, and payer ID 62308 (Cigna)
4. Return coverage status, benefits, copay, and deductible information

CLI Examples:

# Check with Cigna
node dist/cli.js check-eligibility -m "MEMBER123" -f "John" -l "Doe" -d "1990-01-15" -n "1234567890" -p "62308"

# Check with Aetna
node dist/cli.js check-eligibility -m "MEMBER456" -f "Jane" -l "Smith" -d "1985-03-20" -n "1234567890" -p "60054"

# Check with Ambetter
node dist/cli.js check-eligibility -m "MEMBER789" -f "Bob" -l "Williams" -d "1992-07-10" -n "1234567890" -p "68069"

# Use default payer from environment
node dist/cli.js check-eligibility -m "MEMBER123" -f "John" -l "Doe" -d "1990-01-15" -n "1234567890"

Security Considerations

• OAuth tokens are cached server-side and never exposed to Claude
• API credentials stored in environment variables
• All API communications use HTTPS
• Patient Health Information (PHI) handling follows security best practices
• Consider HIPAA compliance requirements for production use

Error Handling

The server includes comprehensive error handling for:

• OAuth authentication failures
• API timeouts and network errors
• Invalid input validation
• Missing or malformed API responses
• Rate limiting and quota errors

Project Structure

src/
├── index.ts                 # Main MCP server entry point
├── services/
│   └── oauth.ts            # OAuth token management
└── tools/
    ├── patientSearch.ts    # Patient API integration
    ├── npiLookup.ts        # NPI Registry integration
    └── eligibilityCheck.ts # Stedi eligibility API integration

License

MIT

Support

For issues or questions, refer to:

• MCP Documentation
• Stedi Healthcare API Docs
• NPI Registry API