MCP Setup Guide

This comprehensive guide will walk you through setting up Model Context Protocol (MCP) integration between Consultia and Claude Desktop.

Prerequisites

Before beginning the setup process, ensure you have:

  1. Claude Desktop Application: Download and install Claude Desktop from claude.ai
  2. Consultia Access: Admin or user account with MCP permissions
  3. Network Access: Ability to connect to your Consultia server
  4. API Key Permissions: Admin access to generate MCP API keys

Step 1: Generate MCP API Key

1.1 Access MCP Settings

  1. Log in to your Consultia account
  2. Navigate to Integrations in the main navigation
  3. Click on MCP Settings card
  4. You'll be redirected to the MCP configuration page

1.2 Create New API Key

  1. In the MCP Settings page, locate the API Key Management section
  2. Click Create New API Key button
  3. Fill in the required information:
    • Name: Enter a descriptive name (e.g., "Claude Desktop Integration")
    • Description: Optional description of the key's purpose
    • Permissions: Select the required permissions:
      • ✅ READ_CUSTOMERS (required for customer data access)
      • ✅ READ_INVOICES (required for invoice data access)
      • ✅ READ_PAYMENTS (required for payment data access)
      • ✅ READ_RESOURCES (optional, for resource data access)
      • ✅ READ_PRODUCTS (optional, for product data access)
      • ✅ EXECUTE_ACTIONS (optional, for business operations)
    • Expiration: Choose expiration date or "Never Expires"
  4. Click Generate API Key

1.3 Copy and Secure API Key

  1. Important: Copy the generated API key immediately
  2. The key will start with ck_ prefix
  3. Store the key securely - it won't be shown again
  4. Click Done to complete the process

Security Note: Never share your API key publicly or commit it to version control.

Step 2: Configure Claude Desktop

2.1 Open Claude Desktop Settings

  1. Launch Claude Desktop application
  2. Click on the Settings icon (gear icon) in the top-right corner
  3. Navigate to Model Context Protocol section

2.2 Add MCP Server

  1. Click Add Server or + button
  2. Fill in the server configuration:
    • Name: "Consultia" (or any descriptive name)
    • URL: Your Consultia server URL
      • Production: https://your-domain.com/api/mcp
      • Development: http://localhost:3000/api/mcp
    • Authentication: Select "API Key"
    • API Key: Paste the API key generated in Step 1

2.3 Test Connection

  1. Click Test Connection to verify the setup
  2. You should see a success message
  3. If connection fails, check:
    • Server URL is correct
    • API key is valid and not expired
    • Network connectivity to the server

2.4 Save Configuration

  1. Click Save to store the MCP server configuration
  2. Claude Desktop will now connect to Consultia

Step 3: Verify Integration

3.1 Test Basic Queries

Once connected, test the integration with simple queries:

  1. List Available Tools:

    What MCP tools are available in Consultia?

  2. Query Customer Data:

    Show me the first 5 customers in our Consultia

  3. Check Analytics:

    What's our current customer count?

3.2 Test Connection in Consultia

  1. Return to Consultia MCP Settings
  2. Use the Connection Tester component
  3. Click Test Connection to verify from Consultia side
  4. Check the Usage Dashboard for API usage statistics

Step 4: Advanced Configuration

4.1 Configure Permissions

Review and adjust API key permissions as needed:

  1. Go to MCP Settings > API Key Management
  2. Find your API key and click Edit
  3. Modify permissions based on your needs:
    • Read-only access: Only READ_* permissions
    • Full access: Include EXECUTE_ACTIONS permission
  4. Click Update to save changes

4.2 Set Up Monitoring

  1. Enable Usage Dashboard: Monitor API usage and performance
  2. Review Audit Logs: Check MCP Settings for operation logs
  3. Set Up Alerts: Configure notifications for unusual activity

4.3 Configure Auto-refresh

  1. In Claude Desktop, enable auto-refresh for real-time data
  2. Set appropriate refresh intervals (e.g., 5-10 minutes)
  3. Monitor performance impact and adjust as needed

Troubleshooting

Common Issues

Connection Failed

Symptoms: Claude Desktop cannot connect to Consultia

Solutions:

  1. Verify server URL is correct and accessible
  2. Check API key is valid and not expired
  3. Ensure network connectivity to the server
  4. Check firewall settings if applicable

Permission Denied

Symptoms: Queries return "Insufficient permissions" error

Solutions:

  1. Review API key permissions in MCP Settings
  2. Add required permissions (READ_CUSTOMERS, etc.)
  3. Regenerate API key with correct permissions
  4. Check user account has MCP access

Slow Performance

Symptoms: Queries take a long time to complete

Solutions:

  1. Check network latency to the server
  2. Optimize queries with specific filters
  3. Use pagination for large datasets
  4. Monitor server performance

Data Not Found

Symptoms: Queries return empty results

Solutions:

  1. Verify data exists in the Consultia
  2. Check filters are not too restrictive
  3. Ensure correct entity names (customers, invoices, etc.)
  4. Verify tenant isolation (consultiaCustomerId)

Getting Help

If you encounter issues not covered in this guide:

  1. Check Audit Logs: Review MCP operation logs in Consultia
  2. Contact Support: Reach out to Consultia support team
  3. Review Documentation: Check the Tool Reference for detailed API information
  4. Community Forum: Visit the Consultia community for user discussions

Security Best Practices

API Key Management

  1. Regular Rotation: Update API keys every 90 days
  2. Principle of Least Privilege: Only grant necessary permissions
  3. Secure Storage: Store API keys in secure password managers
  4. Monitor Usage: Regularly review API usage and audit logs

Network Security

  1. HTTPS Only: Use HTTPS for all production connections
  2. Firewall Rules: Configure firewalls to allow only necessary traffic
  3. VPN Access: Use VPN for remote access if required
  4. Regular Updates: Keep Claude Desktop and Consultia updated

Data Protection

  1. Audit Logging: All MCP operations are logged for security
  2. Data Encryption: All data is encrypted in transit and at rest
  3. Access Control: Implement proper user access controls
  4. Regular Backups: Ensure regular data backups are performed

Next Steps

After successful setup:

  1. Explore Tools: Try different MCP tools and queries
  2. Create Workflows: Build automated workflows using business operations
  3. Generate Reports: Use analytics tools for business intelligence
  4. Train Team: Share setup instructions with your team members
  5. Monitor Usage: Regularly check usage dashboard and audit logs

Related Documentation