How do I use Practice Fusion MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Practice Fusion MCP Server search for patients named John Smith born after 1990" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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:

Contact Practice Fusion Developer Support
- Email: developer-support@practicefusion.com
- Request API access for your practice/organization
Request Required Information
- Client ID and Client Secret
- API URL (typically https://api.practicefusion.com for production)
- Required OAuth scopes for your use case

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

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
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:

Check this README and CLAUDE.md documentation
Review error logs for specific issues
Test with health endpoints to isolate problems
Verify Practice Fusion credentials and permissions
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.