MCPClient

From CaseTalk Wiki
Jump to: navigation, search

MCP Client Configuration Guide

Overview

This guide helps you configure MCP (Model Context Protocol) clients to connect to the CaseTalk MCP Server. Whether you're using Claude Desktop, another MCP-compatible client, or building your own integration, this document covers both secure (HTTPS) and non-secure (HTTP) connection configurations.

Quick Start

Option 1: HTTP (Easiest, Local Development)

{
  "mcpServers": {
    "casetalk": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}


Option 2: HTTPS (Recommended, Secure)

{
  "mcpServers": {
    "casetalk": {
      "url": "https://localhost:8443/mcp",
      "transport": "http",
      "rejectUnauthorized": false
    }
  }
}


Note: See [#https-configuration-with-certificate HTTPS Configuration] for proper certificate trust setup.


Connection Methods

The CaseTalk MCP Server supports multiple connection methods:

Method Protocol Port Security Use Case
HTTP http:// 8080 (default) None Local development, testing
HTTPS https:// 8443 (default) SSL/TLS Production, remote access
stdio Command-line N/A Process isolation Direct process communication

When to Use Each Method

HTTP (No Certificate):

  • ✅ Quick setup for local development
  • ✅ Testing and debugging
  • ✅ Localhost-only access
  • ❌ Not suitable for production
  • ❌ Not secure over network

HTTPS (With Certificate):

  • ✅ Production deployments
  • ✅ Remote access over network
  • ✅ Encrypted communication
  • ✅ Client authentication possible
  • ⚠️ Requires certificate setup
  • ⚠️ Self-signed certificates need trust configuration

stdio:

  • ✅ Maximum security (no network exposure)
  • ✅ Simple configuration
  • ❌ Local machine only
  • ❌ Cannot access remotely


HTTP Configuration (No Certificate)

Server Configuration

  1. Open CaseTalk
  2. Go to: Tools → Options → MCP Server (or wherever SSL config is located)
  3. Uncheck: "Enable SSL/TLS"
  4. Set Port: 8080 (or your preferred port)
  5. Click: Apply

Client Configuration

Claude Desktop Configuration

Location: %APPDATA%\Claude\claudedesktopconfig.json (Windows) or ~/Library/Application Support/Claude/claudedesktopconfig.json (macOS) 

{
  "mcpServers": {
    "casetalk": {
      "url": "http://localhost:8080/mcp",
      "transport": "http",
      "description": "CaseTalk MCP Server (HTTP)"
    }
  }
}


Generic MCP Client Configuration

{
  "server": {
    "url": "http://localhost:8080/mcp",
    "transport": "http"
  }
}


Command-Line Testing

Test your HTTP connection: 

# Test server availability
curl http://localhost:8080/mcp

# Expected response: MCP server information


Advantages of HTTP Mode

✅ Simple Setup: No certificate generation required ✅ Quick Testing: Start using immediately ✅ Easy Debugging: Plain-text traffic, easier to troubleshoot ✅ No Certificate Errors: No trust issues to resolve

Disadvantages of HTTP Mode

❌ No Encryption: Data sent in plain text ❌ Localhost Only: Not safe for remote access ❌ No Authentication: Anyone with network access can connect ❌ Not Production-Ready: Should not be used in production environments

Security Note

⚠️ WARNING: HTTP mode provides no encryption. Only use HTTP for:
- Local development on trusted machines
- Testing purposes
- Localhost-only access
Never expose HTTP mode to a network or the internet!


HTTPS Configuration (With Certificate)

Server Configuration

Step 1: Generate SSL Certificate

  1. Open CaseTalk
  2. Go to: Tools → Options → MCP Server → SSL Configuration
  3. Check: "Enable SSL/TLS"
  4. Verify OpenSSL Status: Should show green ✓ "OpenSSL: OpenSSL 3.x.x"
  1. Enter Common Name:
    • For localhost: localhost
    • For IP access: Your IP address (e.g., 192.168.1.100)
    • For hostname: Your computer hostname (e.g., mycomputer.local)
  1. Set Valid Days: 365 (certificate valid for 1 year)
  2. Click: "Generate Self-Signed Certificate"
  3. Wait: Certificate generation takes a few seconds
  4. Verify: Status shows "Certificate generated successfully"
  5. Set Port: 8443 (or your preferred port)
  6. Click: Apply

Step 2: Locate Certificate

Certificate location: %APPDATA%\CaseTalk12\SSL\server.crt (Windows)

Example: C:\Users\YourName\AppData\Roaming\CaseTalk12\SSL\server.crt

Step 3: Check Certificate Expiration

The SSL Configuration dialog shows certificate status:

  • ✅ Green: "Valid until YYYY-MM-DD (XXX days)"
  • ⚠️ Orange: "Expires in X days - Consider regenerating"
  • ❌ Red: "EXPIRED - Please regenerate"

Client Configuration

Option A: Disable Certificate Verification (Quick Start)

⚠️ Security Note: This bypasses certificate validation. Only use for testing or trusted networks.

Claude Desktop (claudedesktopconfig.json): 

{
  "mcpServers": {
    "casetalk": {
      "url": "https://localhost:8443/mcp",
      "transport": "http",
      "rejectUnauthorized": false,
      "description": "CaseTalk MCP Server (HTTPS - Insecure)"
    }
  }
}


Node.js MCP Client: 

const client = new MCPClient({
  url: 'https://localhost:8443/mcp',
  rejectUnauthorized: false
});


Option B: Trust Certificate (Recommended)

See [#certificate-trust-setup Certificate Trust Setup] for detailed instructions.

Claude Desktop (after trusting certificate): 

{
  "mcpServers": {
    "casetalk": {
      "url": "https://localhost:8443/mcp",
      "transport": "http",
      "description": "CaseTalk MCP Server (HTTPS - Trusted)"
    }
  }
}


Command-Line Testing

Test your HTTPS connection: 

# Test with certificate verification disabled
curl -k https://localhost:8443/mcp

# Test with certificate (after adding to trust store)
curl https://localhost:8443/mcp

# View certificate details
curl -k -v https://localhost:8443/mcp 2>&1 | grep "subject:"


Advantages of HTTPS Mode

✅ Encrypted Communication: All data encrypted in transit ✅ Remote Access: Safe to access over network ✅ Production Ready: Suitable for production use ✅ Client Authentication: Can require client certificates

Disadvantages of HTTPS Mode

⚠️ More Setup: Requires certificate generation ⚠️ Trust Configuration: Self-signed certificates need manual trust ⚠️ Certificate Expiration: Must regenerate certificates annually ⚠️ Port Configuration: May need firewall rules for network access


Certificate Trust Setup

Self-signed certificates are not trusted by default. You must add them to your system's trust store.

Windows

Method 1: Certificate Manager (Recommended)

  1. Locate Certificate:
    • Path: %APPDATA%\CaseTalk12\SSL\server.crt
    • Example: C:\Users\YourName\AppData\Roaming\CaseTalk12\SSL\server.crt
  1. Open Certificate:
    • Double-click server.crt
    • Or right-click → Open
  1. Install Certificate:
    • Click "Install Certificate..."
    • Select "Current User" or "Local Machine"
    • Click "Next"
  1. Choose Certificate Store:
    • Select "Place all certificates in the following store"
    • Click "Browse"
    • Select "Trusted Root Certification Authorities"
    • Click "OK"
  1. Complete Installation:
    • Click "Next"
    • Click "Finish"
    • Click "Yes" to security warning
  1. Verify Installation:
    • Press Win+R
    • Type: certmgr.msc
    • Navigate to: Trusted Root Certification Authorities → Certificates
    • Find your certificate (look for Common Name "localhost" or your hostname)

Method 2: Command Line (PowerShell as Administrator)

# Import certificate to Trusted Root store
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
$cert.Import("$env:APPDATA\CaseTalk12\SSL\server.crt")
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store("Root","CurrentUser")
$store.Open("ReadWrite")
$store.Add($cert)
$store.Close()

Write-Host "Certificate installed successfully!"


macOS

Add Certificate to Keychain

# Add certificate to system keychain
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  ~/Library/Application\ Support/CaseTalk12/SSL/server.crt

# Or add to user keychain
security add-trusted-cert -d -r trustRoot \
  -k ~/Library/Keychains/login.keychain-db \
  ~/Library/Application\ Support/CaseTalk12/SSL/server.crt


GUI Method (Keychain Access)

  1. Open "Keychain Access" app
  2. Go to File → Import Items
  3. Select: ~/Library/Application Support/CaseTalk12/SSL/server.crt
  4. Double-click imported certificate
  5. Expand "Trust" section
  6. Set "When using this certificate" to "Always Trust"
  7. Close window and enter password

Linux

Ubuntu/Debian

# Copy certificate to trusted certificates directory
sudo cp ~/.config/CaseTalk12/SSL/server.crt \
  /usr/local/share/ca-certificates/casetalk.crt

# Update certificate store
sudo update-ca-certificates

# Verify
openssl verify /usr/local/share/ca-certificates/casetalk.crt


Fedora/RHEL/CentOS

# Copy certificate
sudo cp ~/.config/CaseTalk12/SSL/server.crt \
  /etc/pki/ca-trust/source/anchors/casetalk.crt

# Update certificate store
sudo update-ca-trust

# Verify
openssl verify /etc/pki/ca-trust/source/anchors/casetalk.crt


Verify Certificate Trust

After adding certificate to trust store, verify it works: 

# Should connect without -k flag
curl https://localhost:8443/mcp

# If this works without certificate errors, trust is configured correctly!



Troubleshooting

Problem: "OpenSSL Not Found" (Red Warning)

Symptoms:

  • SSL Configuration shows: "OpenSSL: Not detected - Certificate generation will not be available"
  • Generate button is disabled

Solution:

  1. Install OpenSSL from: https://slproweb.com/products/Win32OpenSSL.html
  2. Choose "Win64 OpenSSL v3.x.x Light" (or Win32 for 32-bit)
  3. Run installer
  4. Add to PATH when prompted
  5. Restart CaseTalk
  6. Verify OpenSSL shows green ✓

Problem: "Certificate Expired"

Symptoms:

  • Status shows: "Certificate EXPIRED on YYYY-MM-DD"
  • Cannot enable SSL

Solution:

  1. Click "Generate Self-Signed Certificate" to create new certificate
  2. Apply settings
  3. If using trusted certificate, re-trust the new certificate (see [#certificate-trust-setup Certificate Trust Setup])

Problem: Connection Refused (HTTP)

Symptoms: 

Error: connect ECONNREFUSED 127.0.0.1:8080


Solutions:

  1. Check Server Running: Verify CaseTalk MCP Server is started
  2. Check Port: Ensure port 8080 is correct in both server and client config
  3. Check Firewall: Windows Firewall may block port 8080
    • Open Windows Defender Firewall
    • Allow CaseTalk through firewall
  1. Check Binding: Server may be bound to different interface

Problem: Certificate Errors (HTTPS)

Symptoms: 

Error: self signed certificate
Error: unable to verify the first certificate
Error: DEPTH_ZERO_SELF_SIGNED_CERT


Solutions:

Option 1: Disable Certificate Verification (Quick fix, less secure): 

{
  "mcpServers": {
    "casetalk": {
      "url": "https://localhost:8443/mcp",
      "transport": "http",
      "rejectUnauthorized": false
    }
  }
}


Option 2: Trust Certificate (Recommended):

  • Follow [#certificate-trust-setup Certificate Trust Setup] instructions
  • Restart your MCP client after trusting certificate

Option 3: Use HTTP Instead:

Problem: Wrong Host Name

Symptoms: 

Error: Hostname/IP does not match certificate's altnames
Host: 192.168.1.100. is not in the cert's altnames


Cause: Certificate generated for "localhost" but connecting via IP address (or vice versa)

Solution:

  1. Regenerate certificate with correct Common Name:
  • For IP access: Use IP address (e.g., 192.168.1.100)
  • For hostname: Use hostname (e.g., mycomputer.local)
  • For localhost: Use localhost
  1. Or use the Common Name that matches the certificate:

Problem: Port Already in Use

Symptoms: 

Error: Port 8080 is already in use
Error: Address already in use


Solution:

  1. Change Port: Use different port (e.g., 8081, 8082)
  2. Find Conflicting Process:
   # Windows
   netstat -ano | findstr :8080

   # Linux/macOS
   lsof -i :8080
  1. Stop Conflicting Service: Stop the other service using the port

Problem: Cannot Access from Remote Machine

Symptoms:

  • Works on localhost but not from remote IP
  • Connection timeout from another computer

Solutions: Check Server Binding:

  • Server must bind to 0.0.0.0 (all interfaces), not just 127.0.0.1
  • Check server configuration

Configure Firewall: 

   # Windows Firewall - Allow inbound on port 8443
   New-NetFirewallRule -DisplayName "CaseTalk MCP HTTPS" `
     -Direction Inbound -Protocol TCP -LocalPort 8443 -Action Allow

Use Correct IP:

Certificate Common Name:

  • Regenerate certificate with server's IP or hostname as Common Name
  • Or add IP/hostname to certificate's Subject Alternative Names (SAN)


Security Considerations

Production Deployment Checklist

When deploying CaseTalk MCP Server in production:

Required

  • ✅ Use HTTPS: Always use SSL/TLS encryption
  • ✅ Strong Common Name: Use proper hostname or IP
  • ✅ Firewall Rules: Restrict access to known clients
  • ✅ Certificate Monitoring: Track expiration dates
  • ✅ Access Control: Implement authentication if possible

Recommended

  • ✅ CA-Signed Certificate: Use Let's Encrypt or commercial CA instead of self-signed
  • ✅ Certificate Rotation: Regenerate certificates annually or more frequently
  • ✅ Network Segmentation: Use VPN or private network
  • ✅ Logging: Enable audit logging of connections
  • ✅ Monitoring: Monitor for unauthorized access attempts

Advanced

  • ✅ Client Certificates: Require client certificate authentication
  • ✅ IP Whitelisting: Only allow specific client IPs
  • ✅ Rate Limiting: Prevent abuse
  • ✅ Reverse Proxy: Use nginx or Apache as reverse proxy
  • ✅ Load Balancing: Multiple server instances for availability

Self-Signed vs CA-Signed Certificates

Self-Signed Certificates (Default)

Advantages:

  • ✅ Free
  • ✅ Quick to generate
  • ✅ No external dependencies
  • ✅ Full control

Disadvantages:

  • ❌ Not trusted by default
  • ❌ Browser warnings
  • ❌ Must manually trust on each client
  • ❌ Not suitable for public-facing services

Use For:

  • Development and testing
  • Internal networks
  • Trusted environments
  • Quick prototyping

CA-Signed Certificates (Production)

Advantages:

  • ✅ Automatically trusted
  • ✅ No browser warnings
  • ✅ Professional appearance
  • ✅ Industry standard

Disadvantages:

  • ❌ Costs money (unless Let's Encrypt)
  • ❌ Requires domain name
  • ❌ Renewal process
  • ❌ External dependencies

Use For:

  • Production deployments
  • Public-facing services
  • Commercial applications
  • Enterprise environments

Let's Encrypt Integration (Future)

Note: CaseTalk does not currently support automatic Let's Encrypt certificate generation. Use manual Let's Encrypt certificates if needed:
  1. Generate Let's Encrypt certificate using certbot:
   certbot certonly --standalone -d your-domain.com


  1. Copy certificates to CaseTalk:
   # Certificate
   cp /etc/letsencrypt/live/your-domain.com/fullchain.pem \
      %APPDATA%\CaseTalk12\SSL\server.crt

   # Private key
   cp /etc/letsencrypt/live/your-domain.com/privkey.pem \
      %APPDATA%\CaseTalk12\SSL\server.key


  1. Configure CaseTalk to use these files
  2. Set up auto-renewal cronjob

Security Best Practices

General

  • �� Encrypt Everything: Always use HTTPS in production
  • �� Minimize Exposure: Only expose necessary ports
  • �� Regular Updates: Keep CaseTalk and OpenSSL updated
  • �� Monitor Logs: Review connection logs regularly
  • �� Backup Certificates: Keep secure backups of private keys

Network Security

  • �� Use VPN: Access over VPN when possible
  • �� Private Networks: Keep on private network segment
  • �� No Public Internet: Avoid exposing to public internet
  • �� Firewall: Always use firewall to restrict access

Certificate Management

  • �� Protect Private Keys: Secure server.key file permissions
  • �� Rotate Regularly: Regenerate certificates before expiry
  • �� Monitor Expiration: Set calendar reminders
  • �� Document Locations: Keep inventory of where certificates are deployed


Configuration Examples

Local Development (HTTP)

Server: CaseTalk MCP Server

  • Protocol: HTTP
  • Port: 8080
  • SSL: Disabled

Client: Claude Desktop 

{
  "mcpServers": {
    "casetalk-dev": {
      "url": "http://localhost:8080/mcp",
      "transport": "http",
      "description": "CaseTalk Development Server"
    }
  }
}


Local Development (HTTPS, Self-Signed)

Server: CaseTalk MCP Server

  • Protocol: HTTPS
  • Port: 8443
  • SSL: Enabled
  • Certificate: Self-signed (localhost)

Client: Claude Desktop 

{
  "mcpServers": {
    "casetalk-dev-secure": {
      "url": "https://localhost:8443/mcp",
      "transport": "http",
      "rejectUnauthorized": false,
      "description": "CaseTalk Development Server (HTTPS)"
    }
  }
}


Internal Network (HTTPS, Trusted Certificate)

Server: CaseTalk MCP Server on 192.168.1.100

  • Protocol: HTTPS
  • Port: 8443
  • SSL: Enabled
  • Certificate: Self-signed for 192.168.1.100, trusted on clients

Client: Claude Desktop on 192.168.1.50 

{
  "mcpServers": {
    "casetalk-internal": {
      "url": "https://192.168.1.100:8443/mcp",
      "transport": "http",
      "description": "CaseTalk Internal Server"
    }
  }
}


Production (HTTPS, CA-Signed Certificate)

Server: CaseTalk MCP Server on casetalk.company.com

  • Protocol: HTTPS
  • Port: 443
  • SSL: Enabled
  • Certificate: CA-signed for casetalk.company.com
  • Reverse proxy: nginx

Client: Claude Desktop 

{
  "mcpServers": {
    "casetalk-production": {
      "url": "https://casetalk.company.com/mcp",
      "transport": "http",
      "description": "CaseTalk Production Server"
    }
  }
}


Multiple Environments

Client: Claude Desktop (connecting to multiple CaseTalk instances) 

{
  "mcpServers": {
    "casetalk-dev": {
      "url": "http://localhost:8080/mcp",
      "transport": "http",
      "description": "Local Development"
    },
    "casetalk-staging": {
      "url": "https://staging.casetalk.local:8443/mcp",
      "transport": "http",
      "rejectUnauthorized": false,
      "description": "Staging Environment"
    },
    "casetalk-prod": {
      "url": "https://casetalk.company.com/mcp",
      "transport": "http",
      "description": "Production"
    }
  }
}



Quick Reference

Default Values

Setting Default Value
HTTP Port 8080
HTTPS Port 8443
Certificate Path %APPDATA%\CaseTalk12\SSL\server.crt
Private Key Path %APPDATA%\CaseTalk12\SSL\server.key
Certificate Validity 365 days
Common Name localhost

Configuration File Locations

Platform Claude Desktop Config
Windows %APPDATA%\Claude\claudedesktopconfig.json
macOS ~/Library/Application Support/Claude/claudedesktopconfig.json
Linux ~/.config/Claude/claudedesktopconfig.json

Certificate Locations

Platform CaseTalk Certificate Directory
---------- -------------------------------
Windows %APPDATA%\CaseTalk12\SSL\
macOS ~/Library/Application Support/CaseTalk12/SSL/
Linux ~/.config/CaseTalk12/SSL/

Common Ports

Service HTTP Port HTTPS Port
CaseTalk MCP (Default) 8080 8443
Standard Web 80 443
Alternative 8000 8000

URLs

Type Example
Local HTTP http://localhost:8080/mcp
Local HTTPS https://localhost:8443/mcp
Network HTTP http://192.168.1.100:8080/mcp
Network HTTPS https://192.168.1.100:8443/mcp
Domain HTTPS https://casetalk.company.com/mcp


Getting Help

Documentation

Support

  • GitHub Issues: Report bugs and feature requests
  • Community Forum: Ask questions and share tips
  • Email Support: contact@casetalk.com

Troubleshooting Resources

  • Check server logs in CaseTalk
  • Use curl to test connectivity
  • Use browser to test HTTPS: https://localhost:8443/mcp
  • Check firewall settings
  • Verify certificate with: openssl x509 -in server.crt -text -noout


Appendix

A. OpenSSL Commands

Useful OpenSSL commands for certificate management: 

# View certificate details
openssl x509 -in server.crt -text -noout

# Check certificate expiration
openssl x509 -in server.crt -noout -enddate

# Verify certificate and key match
openssl x509 -in server.crt -noout -modulus | openssl md5
openssl rsa -in server.key -noout -modulus | openssl md5
# (Both should produce same hash)

# Test SSL connection
openssl s_client -connect localhost:8443

# Generate custom certificate (manual)
openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
  -days 365 -nodes -subj "/CN=localhost"


B. Testing Checklist

Before deploying:

  • [ ] Server starts without errors
  • [ ] HTTP connection works (if enabled)
  • [ ] HTTPS connection works (if enabled)
  • [ ] Certificate is valid and not expired
  • [ ] Client can connect successfully
  • [ ] MCP protocol requests work
  • [ ] Firewall rules configured
  • [ ] Certificate trusted on all clients
  • [ ] Expiration date documented
  • [ ] Backup of private key stored securely

C. Glossary

  • MCP: Model Context Protocol - Standard for AI model communication
  • SSL/TLS: Secure Sockets Layer / Transport Layer Security - Encryption protocols
  • Self-Signed Certificate: Certificate signed by its own creator, not a trusted CA
  • CA: Certificate Authority - Trusted organization that signs certificates
  • Common Name (CN): The hostname or IP address the certificate is issued for
  • SAN: Subject Alternative Name - Additional hostnames the certificate covers
  • PEM: Privacy-Enhanced Mail - Certificate encoding format (Base64)
  • Private Key: Secret key that must be kept secure
  • Public Certificate: Public key that can be shared freely
  • Trust Store: System database of trusted certificates
  • Certificate Chain: Hierarchy of certificates from root CA to end certificate


Document Version: 1.0 Last Updated: 2025-01-15 Applies To: CaseTalk 12.x with MCP Server support Author: CaseTalk Development Team

Retrieved from "https://www.casetalk.com/wiki/index.php?title=MCPClient&oldid=2256"