Veradigm-EHR-MCP-server

durvester/Veradigm-EHR-MCP-server

3.1

If you are the rightful owner of Veradigm-EHR-MCP-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Veradigm Unity MCP Server is a remote Model Context Protocol server that provides intelligent access to the Veradigm Unity API for healthcare data integration.

Tools
2
Resources
0
Prompts
0

Veradigm Unity MCP Server

A remote MCP (Model Context Protocol) server using Streamable HTTP transport that provides intelligent access to Veradigm Unity API for healthcare data integration.

Features

  • Remote HTTP Server: Accessible over HTTP using Streamable HTTP transport (not stdio)
  • Intelligent Authentication: User-based authentication with Unity API credentials
  • Automatic Token Management: Handles Unity token acquisition and renewal (20-minute expiration)
  • High-Level Clinical Tools: Meaningful tools that orchestrate multiple Unity API calls
  • Comprehensive Patient Summaries: Aggregates demographics, allergies, problems, medications, vitals, and encounters
  • Smart Patient Search: Search by name, MRN, DOB, or phone number
  • Secure PHI Handling: No PHI logged, secure credential management
  • Session Management: Per-session Unity client instances for multi-user support

Prerequisites

  • Node.js 18+
  • TypeScript
  • Access to Veradigm Unity API endpoint
  • Unity API service credentials
  • Valid EHR/PM user credentials

Installation

  1. Clone this repository

  2. Install dependencies:

    npm install

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

    cp .env.example .env

  4. Edit .env with your Unity API configuration:

    • UNITY_SERVER_URL: Your Unity server URL
    • UNITY_APP_NAME: Your registered Unity application name
    • UNITY_APP_USERNAME: Service account username for GetToken
    • UNITY_APP_PASSWORD: Service account password for GetToken (use quotes if it contains special characters like #)
    • UNITY_EHR_USERNAME: Your EHR user credentials
    • UNITY_EHR_PASSWORD: Your EHR user password

  5. Build the TypeScript code:

    npm run build

Usage

Starting the Server

The MCP server runs as an HTTP server (not stdio):

npm start

Or in development mode with auto-reload:

npm run dev

The server will start on http://localhost:3000 by default. You can change the port using the PORT environment variable:

PORT=8080 npm start

Connecting from MCP Clients

The server uses Streamable HTTP transport and can be accessed at:

http://localhost:3000/mcp
MCP Inspector (for testing)
npx @modelcontextprotocol/inspector http://localhost:3000/mcp
Claude Code
claude mcp add --transport http veradigm-unity http://localhost:3000/mcp
VS Code
code --add-mcp "{\"name\":\"veradigm-unity\",\"type\":\"http\",\"url\":\"http://localhost:3000/mcp\"}"
Cursor

Click this deeplink to add the server:

cursor://anysphere.cursor-deeplink/mcp/install?name=veradigm-unity&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAvbWNwIn0=
Claude Desktop (if using HTTP support)

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "veradigm-unity": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Note: As of now, Claude Desktop primarily supports stdio transport. Use MCP Inspector or other clients that support Streamable HTTP.

Authentication Flow

Environment-Based Authentication:

The server authenticates with the Veradigm Unity API using credentials configured in your .env file:

  1. Application Authentication: The server uses UNITY_APP_USERNAME and UNITY_APP_PASSWORD to obtain a security token from the Unity API (GetToken)
  2. User Authentication: The server then authenticates the EHR user using UNITY_EHR_USERNAME and UNITY_EHR_PASSWORD (GetUserAuthentication)
  3. Session Management: The authenticated session is maintained with automatic token refresh
  4. Automatic Startup: Authentication happens automatically when the server starts - no manual authentication steps required

Security Notes:

  • Store your .env file securely - it contains sensitive credentials
  • Never commit your .env file to version control (it's in .gitignore)
  • Tokens expire after 20 minutes of inactivity and are automatically refreshed
  • The server maintains a single authenticated session for all MCP connections

Available Tools

get_patient_summary

Fetch LLM-optimized patient summary with clinical relationships, timeline, and narrative format.

  • Parameters:

    • patientId (required): Patient ID to retrieve summary for
    • format (optional): Response format - structured (JSON only), narrative (markdown summary), or both (default)

  • Returns: Comprehensive patient summary with:

    • Consistent camelCase Fields: patientId, firstName, allergyId, problemId, etc.
    • Clinical Relationships: Links between data (e.g., diabetes problem → metformin medication)
    • Chronological Timeline: Temporal sequence of clinical events
    • Data Quality Metadata: Sources queried, success/failure tracking, warnings
    • Optional Narrative: Markdown-formatted clinical summary
    • Structured Data: Normalized JSON with demographics, allergies, problems, medications, vitals, encounters

  • Example Response Structure:

    {
  "patient": { "patientId": "123", "firstName": "John", "lastName": "Doe", ... },
  "allergies": [...],
  "problems": [...],
  "medications": [...],
  "recentVitals": {...},
  "recentEncounters": [...],
  "relationships": [
    {
      "type": "problem_to_medication",
      "fromType": "problem",
      "fromId": "diabetes-id",
      "toType": "medication",
      "toId": "metformin-id",
      "description": "Metformin prescribed for Type 2 Diabetes"
    }
  ],
  "timeline": [
    { "date": "2025-11-01", "category": "problem", "event": "Diagnosed with Type 2 Diabetes" },
    { "date": "2025-11-05", "category": "medication", "event": "Started Metformin 500mg BID" }
  ],
  "metadata": {
    "dataSourcesQueried": 6,
    "dataSourcesSuccessful": 6,
    "dataSourcesFailed": []
  },
  "narrative": "# Patient Summary: John Doe\n**MRN:** 12345 | **DOB:** 1980-05-15...",
}
search_patients

Search for patients using various criteria.

  • Parameters:
    • searchTerm (required): Search string (name, MRN, etc.)
    • searchType (optional): Type of search - name, mrn, dob, or phone (default: name)
    • maxResults (optional): Maximum number of results to return (default: 20)
  • Returns: Array of matching patients with demographics

Architecture

Project Structure

src/
├── index.ts                      # MCP server entry point with tool registrations
├── api/
│   └── unity-client.ts           # Unity API client with token management
├── tools/
│   ├── patient-summary.ts        # LLM-optimized patient summary with relationships & timeline
│   └── search-patients.ts        # Patient search functionality
├── types/
│   ├── unity.types.ts            # Unity API type definitions & normalizers
│   └── mcp-response.types.ts     # MCP response schemas (camelCase, relationships, timeline)
└── utils/
    ├── logger.ts                 # Logging utility (no PHI)
    ├── error-handler.ts          # Error handling and formatting
    └── unity-response-parser.ts  # Unity API response unwrapping

Key Design Principles

  1. LLM-Optimized Responses: Consistent camelCase naming, clinical relationships, temporal timelines
  2. Working Backwards from LLM: Tools designed for AI consumption, not raw API passthrough
  3. Stateful Session Management: Single authenticated session with automatic token refresh
  4. Data Quality Transparency: Metadata tracking sources queried, success/failure rates, warnings
  5. Graceful Degradation: Return partial data when some Unity actions fail, never fail completely
  6. Dual Format Support: Both narrative (markdown) and structured (JSON) responses
  7. Parallel Data Fetching: Orchestrates multiple API calls efficiently
  8. Robust Error Handling: User-friendly error messages with recovery suggestions
  9. Secure by Default: No PHI in logs, secure credential handling, .env-based configuration

Development

Running Tests

npm test

Linting

npm run lint

Formatting

npm run format

Troubleshooting

Common Issues

  1. Authentication Failed

    • Verify EHR/PM credentials are correct
    • Check if user has Unity API access permissions
    • Ensure GetUserAuthentication is called after GetToken

  2. Token Expired

    • The server automatically renews tokens
    • If issues persist, use logout and re-authenticate

  3. Network Errors

    • Verify Unity server URL in .env
    • Check network connectivity to Unity server
    • Ensure using HTTPS for production

  4. Action Not Supported

    • Some actions are EHR-only or PM-only
    • Check Unity API documentation for system requirements

Security Considerations

  • Store .env file securely and never commit to version control
  • Use HTTPS for all Unity API connections in production
  • Implement audit logging for compliance
  • Follow HIPAA guidelines for PHI handling
  • Regular security updates for dependencies

Contributing

Please follow the existing code style and add tests for new features.

License

MIT

Support

For Unity API issues, consult the Veradigm Unity API documentation or contact Veradigm support. For MCP server issues, please open an issue in this repository.