MCPClient

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"

• • If red ⚠️, install OpenSSL from: https://slproweb.com/products/Win32OpenSSL.html

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

• • Try http://127.0.0.1:8080/mcp instead of localhost

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:

• Disable SSL in CaseTalk server configuration
• Change client URL to http://localhost:8080/mcp

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:

• If cert is for "localhost", use https://localhost:8443/mcp
• If cert is for IP, use https://192.168.1.100:8443/mcp

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:

• Find server IP: ipconfig (Windows) or ifconfig (Linux/macOS)
• Use that IP in client: https://192.168.1.100:8443/mcp

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

• CaseTalk Documentation: See application Help menu
• MCP Protocol: https://modelcontextprotocol.org
• OpenSSL: https://www.openssl.org/docs/

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