MCP Security Guide

This comprehensive security guide covers all aspects of securing your Model Context Protocol (MCP) integration with Consultia.

Security Overview

MCP integration provides powerful AI capabilities while maintaining enterprise-grade security. This guide ensures your implementation follows security best practices and compliance requirements.

API Key Security

Key Generation and Storage

Secure Key Generation

  • Cryptographic Security: All API keys are generated using cryptographically secure random number generators
  • Unique Prefix: Keys start with ck_ prefix for easy identification
  • Length: 64-character keys provide 256-bit security
  • Uniqueness: Each key is guaranteed to be unique across the system

Secure Storage

# ❌ Never store keys in plain text files
echo "ck_1234567890abcdef..." > api_key.txt

# ✅ Use secure password managers
# Store in 1Password, LastPass, or similar secure vault

# ✅ Use environment variables (development only)
export CONSULTIA_MCP_KEY="ck_1234567890abcdef..."

# ✅ Use secure key management systems (production)
# AWS Secrets Manager, Azure Key Vault, HashiCorp Vault

Key Rotation

  • Regular Rotation: Update API keys every 90 days
  • Graceful Transition: Support multiple keys during rotation period
  • Immediate Revocation: Ability to revoke compromised keys instantly
  • Audit Trail: All key changes are logged for compliance

Permission Management

Principle of Least Privilege

Grant only the minimum permissions necessary for each use case:

Read-Only Access (Recommended for most users):

  • ✅ READ_CUSTOMERS
  • ✅ READ_INVOICES
  • ✅ READ_PAYMENTS
  • ❌ EXECUTE_ACTIONS

Full Access (Admin users only):

  • ✅ READ_CUSTOMERS
  • ✅ READ_INVOICES
  • ✅ READ_PAYMENTS
  • ✅ READ_RESOURCES
  • ✅ READ_PRODUCTS
  • ✅ EXECUTE_ACTIONS

Permission Descriptions

Permission Description Use Case
READ_CUSTOMERS Query customer information and relationships Customer analysis, reporting
READ_INVOICES Access invoice data and status Financial reporting, billing analysis
READ_PAYMENTS View payment records and history Cash flow analysis, reconciliation
READ_RESOURCES Access resource allocation and worksheets Resource planning, capacity analysis
READ_PRODUCTS Query product catalog and pricing Product analysis, pricing strategy
EXECUTE_ACTIONS Perform business operations Automated workflows, data updates

Key Lifecycle Management

Creation Process

  1. Request Approval: Require manager approval for new API keys
  2. Purpose Documentation: Document the intended use case
  3. Permission Review: Review and approve specific permissions
  4. Secure Distribution: Distribute keys through secure channels
  5. Usage Monitoring: Monitor key usage from day one

Expiration and Renewal

  • Automatic Expiration: Set expiration dates for all keys
  • Renewal Process: Establish clear renewal procedures
  • Grace Period: Provide 7-day grace period before expiration
  • Notification System: Alert users 30 days before expiration

Network Security

Transport Layer Security

HTTPS Requirements

  • Production: HTTPS is mandatory for all connections
  • Development: HTTPS recommended, HTTP allowed for local development
  • Certificate Validation: Valid SSL certificates required
  • TLS Version: Minimum TLS 1.2, prefer TLS 1.3

Connection Security

# ✅ Secure connection example
https://your-domain.com/api/mcp

# ❌ Insecure connection (development only)
http://localhost:3000/api/mcp

Firewall Configuration

Inbound Rules

  • Port 443: Allow HTTPS traffic to MCP endpoint
  • Source IPs: Restrict to known client IP ranges
  • Rate Limiting: Implement rate limiting at firewall level

Outbound Rules

  • Claude Desktop: Allow outbound HTTPS to Consultia
  • DNS Resolution: Allow DNS queries for domain resolution
  • Time Sync: Allow NTP for accurate timestamps

VPN and Network Isolation

Corporate Networks

  • VPN Access: Require VPN for remote access
  • Network Segmentation: Isolate MCP traffic on separate VLAN
  • Intrusion Detection: Monitor for suspicious network activity

Cloud Environments

  • VPC Configuration: Use Virtual Private Cloud for isolation
  • Security Groups: Configure security groups for MCP access
  • Load Balancers: Use secure load balancers with SSL termination

Data Protection

Data Encryption

Encryption at Rest

  • Database Encryption: All Consultia data encrypted at rest
  • Key Management: Encryption keys managed securely
  • Backup Encryption: All backups encrypted with strong algorithms

Encryption in Transit

  • TLS 1.3: Use latest TLS version for transport encryption
  • Certificate Pinning: Implement certificate pinning for additional security
  • Perfect Forward Secrecy: Use ephemeral key exchange

Data Access Controls

Tenant Isolation

  • Multi-tenancy: Strict data isolation between customers
  • consultiaCustomerId: All queries filtered by customer ID
  • Cross-tenant Prevention: Impossible to access other customer data

Row-Level Security

-- Example: Customer data isolation
SELECT * FROM customers 
WHERE consultiaCustomerId = :currentCustomerId
AND isArchived = false;

Data Retention and Deletion

Retention Policies

  • Audit Logs: Retain for 7 years for compliance
  • API Keys: Retain metadata for 2 years after deletion
  • Usage Data: Retain for 1 year for analytics

Data Deletion

  • Right to Deletion: Support customer data deletion requests
  • Secure Deletion: Use secure deletion algorithms
  • Deletion Confirmation: Provide deletion confirmation and audit trail

Audit and Monitoring

Comprehensive Logging

Audit Log Fields

{
  "timestamp": "2024-03-15T10:30:00Z",
  "api_key_id": "key_123456",
  "user_id": "user_789",
  "consultia_customer_id": "customer_456",
  "action": "query_crm_data",
  "entity": "customers",
  "filters": {"isArchived": false},
  "result_count": 25,
  "execution_time_ms": 67,
  "ip_address": "192.168.1.100",
  "user_agent": "Claude-Desktop/1.0.0",
  "success": true,
  "error_message": null
}

Log Retention

  • Real-time Logging: All operations logged immediately
  • Centralized Storage: Logs stored in secure, centralized system
  • Search and Analysis: Full-text search and analytics capabilities
  • Compliance Reporting: Automated compliance reports

Monitoring and Alerting

Performance Monitoring

  • Response Times: Monitor API response times
  • Error Rates: Track error rates and types
  • Usage Patterns: Analyze usage patterns for anomalies
  • Resource Utilization: Monitor server resource usage

Security Monitoring

  • Failed Authentication: Alert on multiple failed attempts
  • Unusual Usage: Detect unusual API usage patterns
  • Permission Violations: Alert on permission denial attempts
  • Rate Limit Exceeded: Monitor rate limit violations

Alert Configuration

# Example alert configuration
alerts:
  - name: "Multiple Failed Logins"
    condition: "failed_auth_attempts > 5 in 5 minutes"
    action: "email_admin, block_ip"
    
  - name: "Unusual API Usage"
    condition: "api_calls > 1000 in 1 hour"
    action: "email_admin, log_incident"
    
  - name: "Permission Denied"
    condition: "permission_denied > 10 in 1 hour"
    action: "email_admin, review_permissions"

Compliance and Governance

Regulatory Compliance

GDPR Compliance

  • Data Processing: Clear documentation of data processing purposes
  • Consent Management: Proper consent collection and management
  • Data Portability: Support for data export requests
  • Right to Deletion: Implement data deletion capabilities

SOC 2 Compliance

  • Security Controls: Implement comprehensive security controls
  • Access Management: Proper access control and monitoring
  • Change Management: Documented change management procedures
  • Incident Response: Established incident response procedures

Industry Standards

  • ISO 27001: Information security management
  • PCI DSS: Payment card industry compliance (if applicable)
  • HIPAA: Healthcare data protection (if applicable)

Governance Framework

Security Policies

  • API Key Policy: Documented API key management procedures
  • Access Control Policy: Clear access control guidelines
  • Data Protection Policy: Comprehensive data protection procedures
  • Incident Response Policy: Established incident response procedures

Regular Reviews

  • Quarterly Security Reviews: Comprehensive security assessments
  • Annual Penetration Testing: Regular security testing
  • Compliance Audits: Regular compliance verification
  • Risk Assessments: Periodic risk assessments

Incident Response

Security Incident Types

API Key Compromise

Detection:

  • Unusual usage patterns
  • Access from unknown IP addresses
  • Multiple failed authentication attempts

Response:

  1. Immediately revoke compromised key
  2. Generate new key for legitimate user
  3. Investigate source of compromise
  4. Update security controls if needed
  5. Document incident and lessons learned

Unauthorized Access

Detection:

  • Access to unauthorized data
  • Permission violation attempts
  • Unusual query patterns

Response:

  1. Block unauthorized access
  2. Review and update permissions
  3. Investigate access attempt
  4. Implement additional controls
  5. Notify affected parties

Incident Response Procedures

Immediate Response (0-1 hour)

  1. Assess Impact: Determine scope and severity
  2. Contain Threat: Stop ongoing unauthorized access
  3. Preserve Evidence: Secure logs and evidence
  4. Notify Stakeholders: Alert security team and management

Short-term Response (1-24 hours)

  1. Investigate Root Cause: Determine how incident occurred
  2. Implement Fixes: Apply security patches and updates
  3. Monitor Systems: Enhanced monitoring for similar threats
  4. Update Documentation: Document incident details

Long-term Response (1-30 days)

  1. Post-incident Review: Comprehensive analysis
  2. Process Improvements: Update security procedures
  3. Training Updates: Update security training materials
  4. Compliance Reporting: Submit required compliance reports

Best Practices Summary

For Administrators

  1. Regular Key Rotation: Update API keys every 90 days
  2. Permission Reviews: Quarterly permission reviews
  3. Security Monitoring: Continuous security monitoring
  4. Incident Preparedness: Regular incident response drills

For Users

  1. Secure Key Storage: Store keys in secure password managers
  2. Permission Awareness: Understand granted permissions
  3. Usage Monitoring: Monitor personal API usage
  4. Security Reporting: Report suspicious activity immediately

For Developers

  1. Secure Development: Follow secure coding practices
  2. Input Validation: Validate all input parameters
  3. Error Handling: Implement secure error handling
  4. Security Testing: Regular security testing in development

Security Checklist

Initial Setup

  • Generate API keys with minimal required permissions
  • Configure HTTPS for all connections
  • Set up audit logging and monitoring
  • Implement rate limiting
  • Configure firewall rules

Ongoing Maintenance

  • Rotate API keys every 90 days
  • Review permissions quarterly
  • Monitor audit logs daily
  • Update security patches monthly
  • Conduct security reviews quarterly

Compliance

  • Document security policies
  • Implement data retention policies
  • Conduct regular compliance audits
  • Maintain incident response procedures
  • Provide security training to users

Related Documentation