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

Open CaseTalk
Go to: Tools → Options → MCP Server (or wherever SSL config is located)
Uncheck: "Enable SSL/TLS"
Set Port: 8080 (or your preferred port)
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

Open CaseTalk
Go to: Tools → Options → MCP Server → SSL Configuration
Check: "Enable SSL/TLS"
Verify OpenSSL Status: Should show green ✓ "OpenSSL: OpenSSL 3.x.x"

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

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)

Set Valid Days: 365 (certificate valid for 1 year)
Click: "Generate Self-Signed Certificate"
Wait: Certificate generation takes a few seconds
Verify: Status shows "Certificate generated successfully"
Set Port: 8443 (or your preferred port)
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)

Locate Certificate:

- Path: %APPDATA%\CaseTalk12\SSL\server.crt
- Example: C:\Users\YourName\AppData\Roaming\CaseTalk12\SSL\server.crt

Open Certificate:

- Double-click server.crt
- Or right-click → Open

Install Certificate:

- Click "Install Certificate..."
- Select "Current User" or "Local Machine"
- Click "Next"

Choose Certificate Store:

- Select "Place all certificates in the following store"
- Click "Browse"
- Select "Trusted Root Certification Authorities"
- Click "OK"

Complete Installation:

- Click "Next"
- Click "Finish"
- Click "Yes" to security warning

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)

Open "Keychain Access" app
Go to File → Import Items
Select: ~/Library/Application Support/CaseTalk12/SSL/server.crt
Double-click imported certificate
Expand "Trust" section
Set "When using this certificate" to "Always Trust"
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:

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

Problem: "Certificate Expired"

Symptoms:

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

Solution:

Click "Generate Self-Signed Certificate" to create new certificate
Apply settings
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:

Check Server Running: Verify CaseTalk MCP Server is started
Check Port: Ensure port 8080 is correct in both server and client config
Check Firewall: Windows Firewall may block port 8080

- Open Windows Defender Firewall
- Allow CaseTalk through firewall

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:

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

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:

Change Port: Use different port (e.g., 8081, 8082)
Find Conflicting Process:

   # Windows
   netstat -ano | findstr :8080

   # Linux/macOS
   lsof -i :8080

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

✅ 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:

Generate Let's Encrypt certificate using certbot:

   certbot certonly --standalone -d your-domain.com

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

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

Security Best Practices

General

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

Network Security

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

Certificate Management

&#55357;&#56594; Protect Private Keys: Secure server.key file permissions
&#55357;&#56594; Rotate Regularly: Regenerate certificates before expiry
&#55357;&#56594; Monitor Expiration: Set calendar reminders
&#55357;&#56594; 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