Practice Fusion MCP Server

A comprehensive Model Context Protocol (MCP) server that provides healthcare tools, resources, and prompts for interacting with Practice Fusion EHR using any MCP client. Supports both STDIO (traditional) and HTTP (remote-capable) transports.

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Practice Fusion API credentials (optional at startup - see Getting Practice Fusion Credentials)

Installation & Build

git clone <repository-url>
cd practice-fusion-mcp-server
npm install
npm run build

Basic Usage (STDIO Mode)

# Start server in STDIO mode (default) - no credentials needed at startup
node build/index.js

# OAuth will trigger when tools/resources are accessed
# Configure credentials in .env for Practice Fusion integration

HTTP Mode (Remote Access)

# Set environment for HTTP transport
export TRANSPORT_TYPE=http
export HTTP_PORT=3000

# Start HTTP server - no credentials needed at startup
node build/index.js

# Server available at:
# Health: http://127.0.0.1:3000/health  ← Works immediately
# Status: http://127.0.0.1:3000/status   ← Works immediately  
# MCP: http://127.0.0.1:3000/mcp         ← Works immediately

🏥 Features

Complete Practice Fusion Integration

• 19 Practice Fusion Tools: Patient search, scheduling, demographics, insurance management
• MCP Resources System: Structured data access (facilities, patient profiles, schedules)
• MCP Prompts System: 9 workflow templates for common healthcare tasks
• OAuth2 Authentication: Secure Practice Fusion API access with automatic token refresh

Dual Transport Support

• STDIO Transport: Traditional MCP transport for local clients (Claude Desktop)
• HTTP Transport: Remote-capable HTTP transport with SSE streaming (NEW!)

Enterprise Features

• Session Management: Secure session handling with configurable timeout
• Security Middleware: CORS, Origin validation, Rate limiting
• Health Monitoring: Health check and status endpoints
• Comprehensive Logging: Structured logging with debug modes

🛠️ Available Tools (19 Total)

Patient Management

• search_patients - Search patients by name, DOB, demographics, or identifiers
• get_patient_v4 - Get complete patient details with profile, contact, demographics
• create_patient_v4 - Register new patients with validation
• update_patient_v4 - Update patient information (demographics, contact, insurance)
• get_patient_insurance_plans - Retrieve patient insurance coverage details
• create_patient_insurance_plan - Add new insurance plans for patients

Scheduling & Calendar

• query_events - Query appointments and calendar events with filtering
• get_event - Get detailed appointment information by event ID
• create_event - Schedule new appointments with validation
• update_event - Modify existing appointments (time, status, details)
• get_event_types - List available appointment types and categories
• get_event_confirmation - Retrieve appointment confirmation details
• update_event_confirmation - Update appointment confirmation status

Practice Administration

• get_users - List all practice users and providers with profiles
• get_facilities - Get practice facilities with locations and contact information
• find_payers - Search insurance payers and coverage plans

Document Management

• get_document_types - List available document types for practice
• get_document - Retrieve specific documents by ID
• create_document - Upload and create new documents

📋 MCP Resources (Structured Data Access)

Practice Resources

• practice://facilities - All practice facilities with locations and details
• practice://users - Complete users and providers directory
• practice://event-types - Available appointment types and categories

Patient Resources (Dynamic)

• patient://profile/{patientGuid} - Patient demographics and contact information
• patient://insurance/{patientGuid} - Patient insurance plans and coverage

Calendar Resources (Dynamic)

• calendar://schedule/{facilityGuid}/{date} - Daily facility schedule (YYYY-MM-DD)
• calendar://availability/{ehrUserGuid}/{startDate}/{endDate} - Provider availability

Payer Resources

• payers://directory - Insurance payers directory with available plans

📝 MCP Prompts (Workflow Templates)

Scheduling Workflows

• schedule-appointment - Interactive appointment scheduling with validation
• reschedule-appointment - Appointment rescheduling with conflict checking
• check-availability - Provider availability analysis and optimization

Patient Management Workflows

• patient-intake - New patient registration workflow with insurance setup
• update-patient-info - Guided patient information updates
• insurance-verification - Step-by-step insurance verification and setup

Administrative Workflows

• daily-schedule-review - Comprehensive daily schedule analysis
• patient-search-optimization - Search strategy guidance and best practices
• appointment-status-update - Appointment status management workflow

⚙️ Configuration

Getting Practice Fusion Credentials

To use this MCP server, you need Practice Fusion API credentials:

1. Contact Practice Fusion Developer Support

   • Email: developer-support@practicefusion.com
   • Request API access for your practice/organization

2. Request Required Information

   • Client ID and Client Secret
   • API URL (typically https://api.practicefusion.com for production)
   • Required OAuth scopes for your use case

3. Scopes You'll Need

   calendar:a_confirmation_v1 calendar:a_events_v1 calendar:a_events_v2
   calendar:a_notes_v1 calendar:a_status_v1 calendar:d_events_v1
   calendar:r_events_v1 calendar:r_events_v2 calendar:r_eventtypes_v1
   patient:a_contact_v4 patient:a_demographics_v1 patient:a_insurance_plan_v1
   patient:r_profile_v4 patient:r_contact_v4 patient:r_search_v2
   practice:r_facilities_v2 user:r_login_v2 user:r_profile_v2
   payer:r_insurance_v1 document:r_document_v2
   

Environment Configuration

Create a .env file in the project root:

# ========================================
# PRACTICE FUSION API CREDENTIALS
# ========================================
# REQUIRED: Get these from Practice Fusion Developer Support
PF_CLIENT_ID=your_client_id_here
PF_CLIENT_SECRET=your_client_secret_here

# ========================================
# PRACTICE FUSION API CONFIGURATION
# ========================================
# API Base URL (default: QA environment)
PF_API_URL=https://qa-api.practicefusion.com

# OAuth Endpoints (usually don't need to change)
PF_TOKEN_PATH=/ehr/oauth2/token
PF_AUTHORIZE_PATH=/ehr/oauth2/auth

# OAuth Callback (for local development)
PF_CALLBACK_URL=http://localhost:3456/oauth/callback
PF_CALLBACK_PORT=3456

# API Scopes (copy the scopes provided by Practice Fusion)
PF_SCOPES="calendar:a_confirmation_v1 calendar:a_events_v1 calendar:a_events_v2 calendar:a_notes_v1 calendar:a_status_v1 calendar:d_events_v1 calendar:r_events_v1 calendar:r_events_v2 calendar:r_eventtypes_v1 calendar:r_notes_v1 chart:a_superbill_v2 chart:a_vxu_v2 document:a_document_v2 document:r_document_types_v2 document:r_document_v2 document:z_document_v2 encounter:a_diagnosis_v1 encounter:a_notes_v1 encounter:r_metadata_v1 encounter:r_summary_v1 me:r_erx_v2 me:r_login_v2 me:r_profile_v2 patient:a_contact_v4 patient:a_demographics_v1 patient:a_guarantor_v1 patient:a_insurance_plan_v1 patient:a_preferredPharmacy_v1 patient:a_relatedPerson_v1 patient:r_ccda_allergies_v2 patient:r_ccda_assessmentAndPlan_v2 patient:r_ccda_clinicalNotes_v2 patient:r_ccda_demographics_v2 patient:r_ccda_encounters_v2 patient:r_ccda_functionalStatus_v2 patient:r_ccda_goals_v2 patient:r_ccda_healthConcerns_v2 patient:r_ccda_immunizations_v2 patient:r_ccda_medicalEquipment_v2 patient:r_ccda_medications_v2 patient:r_ccda_mentalStatus_v2 patient:r_ccda_problems_v2 patient:r_ccda_procedures_v2 patient:r_ccda_reasonForReferral_v2 patient:r_ccda_results_v2 patient:r_ccda_socialHistory_v2 patient:r_ccda_vitalSigns_v2 patient:r_contact_v4 patient:r_demographics_v2 patient:r_diagnosis_v1 patient:r_guarantor_v1 patient:r_insurance_v3 patient:r_insurance_plan_v1 patient:r_preferredPharmacy_v1 patient:r_profile_v4 patient:r_relatedPerson_v1 patient:r_search_v2 payer:r_insurance_v1 payer:r_insurance_plan_v1 practice:r_facilities_v2 user:r_login_v2 user:r_profile_v2"

# ========================================
# TRANSPORT CONFIGURATION
# ========================================
# Transport Type: 'stdio' (default) or 'http'
TRANSPORT_TYPE=stdio

# HTTP Transport Settings (only used when TRANSPORT_TYPE=http)
HTTP_PORT=3000
HTTP_HOST=127.0.0.1
HTTP_ALLOWED_ORIGINS=http://localhost:*,https://localhost:*
HTTP_REQUIRE_ORIGIN_VALIDATION=true
HTTP_ENABLE_CORS=true
HTTP_SESSION_TIMEOUT_MS=1800000

Security Notes

• Never commit credentials to version control
• .env file is gitignored for security
• Use environment variables in production deployments
• Restrict HTTP_HOST to localhost (127.0.0.1) unless external access needed

🖥️ Transport Modes

STDIO Transport (Default)

For local MCP clients like Claude Desktop:

# Default mode - no configuration needed
node build/index.js

HTTP Transport (Remote Access)

For web applications and remote integrations:

# Enable HTTP transport
export TRANSPORT_TYPE=http
export HTTP_PORT=3000
export HTTP_HOST=127.0.0.1

# Start HTTP server
node build/index.js

# Available endpoints:
# http://127.0.0.1:3000/health   - Health check
# http://127.0.0.1:3000/status   - Server status
# http://127.0.0.1:3000/mcp      - MCP endpoint

Quick HTTP Test

# Use provided test script
./start-http-test.sh

# Manual health check
curl http://127.0.0.1:3000/health

HTTP Transport Testing

Build Command

npm run build

Test HTTP Transport Functionality

# Automated test suite
./test-http-only.sh

# Manual server start for testing
./start-http-test.sh

Manual HTTP Testing

# 1. Start server in HTTP mode
export TRANSPORT_TYPE=http
export HTTP_PORT=3000
export PF_CLIENT_ID=test
export PF_CLIENT_SECRET=test
node build/index.js

# 2. Test health endpoint
curl http://127.0.0.1:3000/health

# 3. Test initialization
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "Test Client", "version": "1.0.0"}
    }
  }'

🔗 Integration Examples

Claude Desktop (STDIO Mode)

Add to Claude Desktop configuration:

{
  "mcpServers": {
    "practice-fusion": {
      "command": "node",
      "args": ["/path/to/practice-fusion-mcp-server/build/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Important: Credentials are read from .env file, not Claude Desktop config for security.

HTTP Client Integration (JavaScript)

// Initialize MCP session
const initResponse = await fetch('http://127.0.0.1:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'MCP-Protocol-Version': '2025-06-18'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'initialize',
    params: {
      protocolVersion: '2025-06-18',
      capabilities: {},
      clientInfo: { name: 'My App', version: '1.0.0' }
    }
  })
});

const sessionId = initResponse.headers.get('Mcp-Session-Id');

// Use tools with session
const searchResponse = await fetch('http://127.0.0.1:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'MCP-Protocol-Version': '2025-06-18',
    'Mcp-Session-Id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2,
    method: 'tools/call',
    params: {
      name: 'search_patients',
      arguments: { FirstName: 'John', LastName: 'Smith' }
    }
  })
});

Server-Sent Events (SSE) Example

// Open SSE connection for real-time updates
const eventSource = new EventSource(
  `http://127.0.0.1:3000/mcp?Mcp-Session-Id=${sessionId}`
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

eventSource.addEventListener('response', (event) => {
  const response = JSON.parse(event.data);
  // Handle JSON-RPC response
});

🧪 Development & Testing

Development Commands

npm run build          # TypeScript compilation
npm run watch          # Watch mode for development
npm run inspector      # Launch MCP Inspector

MCP Inspector (Development Tool)

# Install globally
npm install -g @modelcontextprotocol/inspector

# Launch inspector
npx @modelcontextprotocol/inspector build/index.js

# Access at http://localhost:5173

Testing Scripts

# Test HTTP transport functionality
./test-http-only.sh

# Start HTTP server for manual testing
./start-http-test.sh

# Test specific Practice Fusion APIs (requires real credentials)
npm run build && node build/test-pf-apis.js

Environment Variables for Testing

# HTTP Transport Testing
export TRANSPORT_TYPE=http
export HTTP_PORT=3000
export HTTP_HOST=127.0.0.1
export HTTP_REQUIRE_ORIGIN_VALIDATION=false  # Disable for testing
export HTTP_ENABLE_CORS=true

# Use dummy credentials for HTTP transport testing
export PF_CLIENT_ID=test-client-id
export PF_CLIENT_SECRET=test-client-secret

🔧 Troubleshooting

Common Issues

Build Errors

# Clear build cache
rm -rf build/
npm run build

Port Conflicts

# Check if port is in use
lsof -i :3000
lsof -i :3456  # OAuth callback port

# Kill process using port
kill -9 $(lsof -t -i:3000)

HTTP Transport Issues

# Check configuration
echo $TRANSPORT_TYPE $HTTP_PORT $HTTP_HOST

# Test health endpoint
curl http://127.0.0.1:3000/health

# Check server logs
TRANSPORT_TYPE=http node build/index.js

Practice Fusion Authentication

# Verify credentials are set
echo $PF_CLIENT_ID $PF_CLIENT_SECRET

# Check .env file exists and is loaded
cat .env | grep PF_

# Test with debug logging
DEBUG=* node build/index.js

Session Issues (HTTP Mode)

# Check session status
curl http://127.0.0.1:3000/status

# Clear sessions (restart server)
# Sessions are in-memory and cleared on restart

Debug Mode

# Enable detailed logging
DEBUG=* node build/index.js

# HTTP transport with debug logs
DEBUG=* TRANSPORT_TYPE=http node build/index.js

🚀 Production Deployment

Environment Setup

# Production environment variables
TRANSPORT_TYPE=http
HTTP_HOST=0.0.0.0                    # Bind to all interfaces
HTTP_PORT=3000
HTTP_REQUIRE_ORIGIN_VALIDATION=true  # Enable security
HTTP_ALLOWED_ORIGINS=https://yourdomain.com
HTTP_SESSION_TIMEOUT_MS=3600000      # 1 hour

Docker Example

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build/ ./build/
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "build/index.js"]

Security Recommendations

• Use HTTPS in production with proper SSL certificates
• Configure firewall to restrict access
• Set up monitoring for health endpoints
• Use reverse proxy (nginx, Apache) for advanced features
• Implement log aggregation for monitoring

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Development Guidelines

• Follow TypeScript best practices
• Add tests for new features
• Update documentation
• Test both STDIO and HTTP transports
• Ensure no credentials in code

📞 Support

For support and questions:

1. Check this README and CLAUDE.md documentation
2. Review error logs for specific issues
3. Test with health endpoints to isolate problems
4. Verify Practice Fusion credentials and permissions
5. Check MCP client compatibility

📚 Additional Documentation

• CLAUDE.md - Comprehensive technical documentation
• HTTP Transport Details - In-depth HTTP implementation guide
• Security Considerations - Security best practices
• Integration Examples - More detailed integration examples

---

⚠️ Security Notice: This server handles healthcare data. Ensure compliance with HIPAA and other healthcare regulations in your deployment. Never commit credentials to version control.