Laravel Healthcare MCP Server

A comprehensive Model Context Protocol (MCP) server that acts as a proxy/router for a Laravel healthcare API with Sanctum authentication. This server provides seamless integration between MCP clients and the Laravel healthcare application, supporting all 8 user roles and 400+ API endpoints.

🚀 Features

• Complete API Coverage: 400+ endpoints from Laravel healthcare application
• 9 Authentication Types: Admin, Agent, Patient, Practitioner, Affiliate, Partner, Network, Doctor, Provider
• Automatic Token Management: Sanctum token storage and refresh
• HIPAA Compliance: Sensitive data masking and secure logging
• Comprehensive Error Handling: Healthcare-specific error responses
• Real-time Monitoring: Health checks and performance metrics
• Retry Logic: Exponential backoff for failed requests
• Validation: Joi schemas for all endpoint parameters

📋 Prerequisites

• Node.js 18.0.0 or higher
• Access to Laravel healthcare API
• Valid authentication credentials for desired user roles

🛠️ Installation

1. Clone or extract the server directory:

2. Install dependencies:

   npm install
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your configuration
   

4. Validate configuration:

   npm run validate-config
   

⚙️ Configuration

Required Environment Variables

# Laravel API Configuration
LARAVEL_API_BASE_URL=https://your-healthcare-api.com

# At least one authentication type must be configured
ADMIN_USERNAME=admin@healthcare.com
ADMIN_PASSWORD=your_admin_password

# Additional auth types as needed...

Authentication Types

The server supports 9 authentication types. Configure credentials for the roles you need:

Role	Username Variable	Password Variable	Default Endpoint
Admin	ADMIN_USERNAME	ADMIN_PASSWORD	/api/admin/login
Agent	AGENT_USERNAME	AGENT_PASSWORD	/agent/login/post
Patient	PATIENT_USERNAME	PATIENT_PASSWORD	/api/frontend/login
Practitioner	PRACTITIONER_USERNAME	PRACTITIONER_PASSWORD	/api/practitioner/login
Affiliate	AFFILIATE_USERNAME	AFFILIATE_PASSWORD	/api/affiliate/login
Partner	PARTNER_USERNAME	PARTNER_PASSWORD	/api/partner/login
Network	NETWORK_USERNAME	NETWORK_PASSWORD	/api/network/login
Doctor	DOCTOR_USERNAME	DOCTOR_PASSWORD	/api/doctor/login
Provider	PROVIDER_USERNAME	PROVIDER_PASSWORD	/api/provider/login

Optional Configuration

# Server Configuration
MCP_SERVER_NAME=laravel-healthcare-mcp-server
MCP_SERVER_VERSION=1.0.0
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=0.0.0.0

# API Client Settings
LARAVEL_API_TIMEOUT=30000
LARAVEL_API_RETRY_ATTEMPTS=3
LARAVEL_API_RETRY_DELAY=1000

# Token Management
TOKEN_REFRESH_BUFFER=300

# Logging
LOG_LEVEL=info
ENABLE_REQUEST_LOGGING=true
MASK_SENSITIVE_DATA=true

# Security
HIPAA_COMPLIANCE_MODE=true
ENABLE_DETAILED_ERRORS=false

🚀 Usage

Starting the Server

The server supports three transport modes:

1. Both Modes (Recommended - stdio + HTTP simultaneously):

# Default mode - both transports running simultaneously
npm start

# Explicitly set both modes
npm run start:both

# Development mode with auto-restart
npm run dev:both

2. Stdio Mode Only (for MCP clients like Claude Desktop):

# Stdio transport only
npm run start:stdio

# Development mode with auto-restart
npm run dev:stdio

3. HTTP Mode Only (for web-based clients):

# HTTP transport only
npm run start:http

# Development mode with auto-restart
npm run dev:http

Transport Configuration

Set the transport mode in your .env file:

# For both MCP clients and HTTP/web clients (recommended)
MCP_TRANSPORT=both

# For MCP clients only (Claude Desktop, VS Code MCP extensions)
MCP_TRANSPORT=stdio

# For HTTP/web clients only
MCP_TRANSPORT=http

Server URLs (HTTP Mode)

When running in HTTP mode, you can access:

• Health Check: http://localhost:3000/health
• MCP Protocol: POST http://localhost:3000/mcp (JSON-RPC 2.0)
• Tools List: http://localhost:3000/tools
• Server Stats: http://localhost:3000/stats
• Tool Execution: POST http://localhost:3000/tools/{toolName}/execute
• Auth Status: http://localhost:3000/auth/status

Using with MCP Clients

Claude Desktop Configuration:

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "laravel-healthcare": {
      "command": "node",
      "args": ["/path/to/laravel-healthcare-mcp-server/index.js"],
      "env": {
        "LARAVEL_API_BASE_URL": "https://your-api.com",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

VS Code MCP Extension:

Configure the MCP extension to use:

• Command: node
• Args: ["/path/to/laravel-healthcare-mcp-server/index.js"]
• Environment: Set MCP_TRANSPORT=stdio

MCP Protocol Testing

Test tool listing:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Test tool execution:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "public_manage_login",
      "arguments": {
        "email": "test@example.com",
        "password": "password"
      }
    },
    "id": 2
  }'

The server implements the Model Context Protocol and can be used with any MCP-compatible client:

{
  "mcpServers": {
    "laravel-healthcare": {
      "command": "node",
      "args": ["path/to/laravel-healthcare-mcp-server/server.js"]
    }
  }
}

Available Tools

The server automatically generates MCP tools for all API endpoints. Tool names follow the pattern:

• Public endpoints: public_{action}_{resource}
• Authenticated endpoints: {role}_{action}_{resource}

Examples:

• public_create_patient - Register new patient (public)
• admin_get_patient_list - Get patient list (admin only)
• agent_create_appointment - Create appointment (agent only)
• provider_create_getAvailableSlotsData - Get available appointment slots by practitioner ID, month and timezone (provider only)

Tool Categories

Tools are organized into categories:

• Patient Management (150+ tools)
• Appointment Scheduling (50+ tools)
• Medical Records (40+ tools)
• Prescription Management (30+ tools)
• Document Management (25+ tools)
• Messaging (20+ tools)
• Billing & Orders (30+ tools)
• Analytics & Reports (25+ tools)
• User Management (20+ tools)
• Forms & Questionnaires (15+ tools)

🔧 Development

Project Structure

laravel-healthcare-mcp-server/
├── src/
│   ├── auth/           # Authentication management
│   ├── config/         # Configuration and endpoints
│   ├── proxy/          # API client and HTTP handling
│   ├── server/         # MCP server implementation
│   ├── tools/          # Tool generation and execution
│   └── utils/          # Utilities (logging, errors)
├── config/             # Configuration files
├── logs/               # Log files
├── docs/               # Documentation
├── test/               # Test scripts
├── server.js           # Main entry point
├── package.json        # Dependencies and scripts
└── README.md           # This file

Scripts

# Start server
npm start

# Development mode
npm run dev

# Run tests
npm test

# Validate configuration
npm run validate-config

# Generate documentation
npm run docs

# Lint code
npm run lint

Adding New Endpoints

1. Update endpoint registry in src/config/endpoints.js
2. Add authentication configuration if needed
3. Restart server to regenerate tools

Example endpoint definition:

{
  path: '/api/new-endpoint/{id}',
  method: 'POST',
  controller: 'Controller@method',
  category: ENDPOINT_CATEGORIES.PATIENT_MANAGEMENT,
  description: 'Description of the endpoint',
  parameters: {
    id: { type: 'string', required: true, description: 'Resource ID' },
    data: { type: 'object', required: true, description: 'Request data' }
  }
}

🔍 Monitoring

Health Checks

The server provides health check endpoints and logging:

# Check server health (if health endpoint enabled)
curl http://localhost:3000/health

Logging

Logs are written to:

• Console (formatted for development)
• Files (JSON format for production)
• Separate error logs for critical issues

Log levels: error, warn, info, debug

Performance Monitoring

The server tracks:

• Tool execution times
• API response times
• Authentication token refresh cycles
• Error rates by endpoint

🔒 Security

HIPAA Compliance

• Sensitive data masking in logs
• Secure token storage with automatic expiration
• Audit logging for all operations
• Error message sanitization to prevent data leaks

Authentication Security

• Token storage with automatic expiration
• Automatic token refresh before expiration
• Credential validation on startup
• Rate limiting support

🐛 Troubleshooting

Common Issues

1. Authentication Failures

   # Validate credentials
   npm run validate-config
   
   # Check logs for auth errors
   tail -f logs/mcp-server.log | grep auth
   

2. API Connection Issues

   # Test API connectivity
   curl -v $LARAVEL_API_BASE_URL/health
   
   # Check network configuration
   npm run test
   

3. Tool Execution Errors

   # Enable debug logging
   LOG_LEVEL=debug npm start
   
   # Check tool validation
   npm run validate-config
   

Debug Mode

Enable debug mode for detailed logging:

DEBUG_MODE=true
LOG_LEVEL=debug
ENABLE_DETAILED_ERRORS=true

📚 API Documentation

Generated Tools

The server automatically generates tools for all endpoints. Each tool includes:

• Name: Descriptive tool name
• Description: Endpoint purpose and details
• Parameters: JSON schema with validation
• Authentication: Required auth type

Endpoint Categories

Category	Description	Tool Count
Patient Management	Patient registration, profiles, medical history	150+
Appointment Scheduling	Booking, availability, calendar integration	50+
Medical Records	SOAP notes, vitals, clinical documentation	40+
Prescription Management	Medications, dosages, pharmacy integration	30+
Document Management	File uploads, signed documents, sharing	25+
Messaging	Secure messaging, notifications, communication	20+
Billing & Orders	Payments, subscriptions, lab orders	30+
Analytics & Reports	Statistics, exports, business intelligence	25+
User Management	Authentication, profiles, permissions	20+
Forms & Questionnaires	Dynamic forms, intake questionnaires	15+

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

For support and questions:

1. Check the troubleshooting section
2. Review logs for error details
3. Validate configuration
4. Test API connectivity

🔄 Updates

To update the server:

1. Pull latest changes
2. Run npm install for new dependencies
3. Update configuration if needed
4. Restart the server

---

Laravel Healthcare MCP Server - Bridging healthcare APIs with Model Context Protocol