mcp-tool/N8N-SETUP-GUIDE.md

🔧 n8n MCP Client Setup Guide

This guide shows you how to connect n8n to the Laravel Healthcare MCP Server via HTTP.

📋 Prerequisites

1. MCP Server Running: Ensure your Laravel Healthcare MCP Server is running
2. n8n Installed: Have n8n installed and accessible
3. Network Access: n8n can reach the MCP server (usually http://localhost:3000)

🚀 Quick Start

1. Start the MCP Server

cd laravel-healthcare-mcp-server
npm start

The server will start in dual mode (stdio + HTTP) and be available at:

• HTTP Endpoint: http://localhost:3000/mcp
• n8n Info: http://localhost:3000/n8n/info

2. Test Server Connectivity

# Test server health
curl http://localhost:3000/health

# Get n8n-specific information
curl http://localhost:3000/n8n/info

🔌 n8n Integration Methods

Method 1: HTTP Request Node (Recommended)

Step 1: Add HTTP Request Node

• Add an "HTTP Request" node to your n8n workflow
• Set the following parameters:

Basic Configuration:

• Method: POST
• URL: http://localhost:3000/mcp
• Headers:

  {
    "Content-Type": "application/json",
    "Accept": "application/json"
  }
  

Step 2: Initialize MCP Connection

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": {
      "name": "n8n",
      "version": "1.0.0"
    }
  },
  "id": 1
}

Step 3: List Available Tools

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 2
}

Step 4: Execute Healthcare Tools

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "public_manage_login",
    "arguments": {
      "email": "provider@example.com",
      "password": "your_password"
    }
  },
  "id": 3
}

Method 2: Custom n8n Node (Advanced)

For advanced users, you can create a custom n8n node specifically for MCP:

1. Create Node Structure:

   nodes/
   ├── McpClient/
   │   ├── McpClient.node.ts
   │   └── mcp-client.svg
   

2. Node Configuration:

   • Server URL: http://localhost:3000/mcp
   • Protocol: JSON-RPC 2.0
   • Methods: initialize, tools/list, tools/call, ping

📊 Available Healthcare Tools

The MCP server provides 470+ healthcare API tools organized by category:

Authentication Tools

• public_manage_login - Provider login
• patient_login - Patient portal login
• partner_login - Partner authentication

Clinical Tools (Provider Auth Required)

• provider_get_patients - Get patient list
• provider_create_patient - Create new patient
• provider_update_patient - Update patient data
• provider_get_appointments - Get appointments

Patient Portal Tools

• patient_get_profile - Get patient profile
• patient_get_appointments - Get patient appointments
• patient_book_appointment - Book new appointment

Business Tools

• partner_get_analytics - Get business analytics
• affiliate_get_commissions - Get affiliate data
• network_get_providers - Get network providers

🔐 Authentication Flow

1. Login First

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "public_manage_login",
    "arguments": {
      "email": "your-email@example.com",
      "password": "your-password"
    }
  },
  "id": 1
}

2. Token Auto-Storage

The server automatically extracts and stores authentication tokens from login responses.

3. Use Protected Tools

After login, you can use provider-authenticated tools without additional auth.

🧪 Testing Examples

Example 1: Get Patient List

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "provider_get_patients",
    "arguments": {
      "page": 1,
      "limit": 10
    }
  },
  "id": 4
}

Example 2: Create Patient

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "provider_create_patient",
    "arguments": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "dateOfBirth": "1990-01-01",
      "phone": "+1234567890"
    }
  },
  "id": 5
}

🔧 Troubleshooting

Common Issues

1. Connection Refused

   • Ensure MCP server is running: npm start
   • Check server URL: http://localhost:3000/mcp
   • Verify port 3000 is not blocked

2. Authentication Errors

   • Login first using public_manage_login
   • Check credentials are correct
   • Verify token storage in server logs

3. Tool Not Found

   • List available tools: tools/list
   • Check tool name spelling
   • Verify tool exists in current server version

Debug Commands

# Check server status
curl http://localhost:3000/health

# Get server info for n8n
curl http://localhost:3000/n8n/info

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

📚 Additional Resources

• Server Documentation: README.md
• API Reference: MCP-TOOLS-REFERENCE.md
• Example Workflow: n8n-workflow-template.json
• Configuration: n8n-mcp-config.json

🆘 Support

If you encounter issues:

1. Check server logs for errors
2. Verify n8n can reach the server URL
3. Test with curl commands first
4. Check authentication flow