appserver/CLAUDE_DESKTOP_CONFIG.md

Claude Desktop Configuration for SaaS Platform MCP

This guide shows how to configure Claude Desktop to use the SaaS Platform MCP server for programmatic access to your self-hosted SaaS platform.

Prerequisites

1. Your SaaS platform must be running (npm run start)
2. Node.js and npm installed on your host machine
3. Claude Desktop installed

Installation Steps

1. Install MCP Server Globally

cd mcp-server
npm install -g .

This installs the mcp-saas-server command globally.

2. Configure Claude Desktop

macOS

Edit this file: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

Edit this file: %APPDATA%\Claude\claude_desktop_config.json

Linux

Edit this file: ~/.config/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "saas-platform": {
      "command": "mcp-saas-server",
      "env": {
        "SAAS_API_URL": "http://localhost",
        "SAAS_AUTH_URL": "http://localhost/auth", 
        "SAAS_STORAGE_URL": "http://localhost/storage",
        "DEBUG": "false"
      }
    }
  }
}

3. Restart Claude Desktop

Completely quit and restart Claude Desktop for the configuration to take effect.

Usage in Claude

Once configured, you can ask Claude to interact with your SaaS platform:

Authentication Examples

Please login to my SaaS platform using email: admin@saas.local and password: admin123

Show me my current user information

Register a new user with email test@example.com and password password123

Organization Management

List all my organizations

Create a new organization called "My Startup" with slug "my-startup"

Application Management

Show me all applications in the default organization

Create a new TypeScript application with name "My App" and slug "my-app" in the default org

Deploy the application with ID app-uuid-here

File Storage

List all files in the storage

Upload a configuration file with JSON content: {"api_key": "secret123", "timeout": 30}

Platform Monitoring

Check the health of all platform services

Show me platform statistics

Available Tools

The MCP server provides these tools to Claude:

Authentication

• saas_login - Authenticate with the platform
• saas_logout - Logout current session
• saas_get_current_user - Get current user details
• saas_register_user - Register new user account

Organizations

• saas_list_organizations - List user's organizations
• saas_create_organization - Create new organization
• saas_get_organization - Get organization details

Applications

• saas_list_applications - List applications
• saas_create_application - Create new application
• saas_get_application - Get application details
• saas_deploy_application - Deploy application
• saas_get_deployments - Get deployment history

System

• saas_health_check - Check platform health
• saas_get_platform_stats - Get platform statistics

Storage

• saas_list_files - List storage files
• saas_upload_file - Upload files
• saas_download_file - Download files
• saas_delete_file - Delete files

Security Notes

• Your credentials are stored locally in the MCP session only
• Authentication tokens are not persisted
• All operations are logged in the platform's audit logs
• Use strong passwords and change defaults in production

Troubleshooting

MCP Server Not Found

# Verify installation
which mcp-saas-server

# Reinstall if needed
cd mcp-server
npm install -g .

Connection Errors

1. Ensure SaaS platform is running (npm run start)
2. Check URLs in your Claude config match your platform URLs
3. Verify network connectivity between Claude and the platform

Authentication Issues

1. Verify credentials are correct
2. Check that user exists in the platform
3. Try registering a new user if login fails

Debug Mode

Enable debug logging by setting "DEBUG": "true" in your Claude Desktop config:

{
  "mcpServers": {
    "saas-platform": {
      "command": "mcp-saas-server",
      "env": {
        "SAAS_API_URL": "http://localhost",
        "SAAS_AUTH_URL": "http://localhost/auth", 
        "SAAS_STORAGE_URL": "http://localhost/storage",
        "DEBUG": "true"
      }
    }
  }
}

Development Setup

If you want to modify the MCP server:

cd mcp-server
npm install
npm run dev

# Test with MCP Inspector
npm install -g @modelcontextprotocol/inspector
mcp-inspector dist/index.js

Production Usage

For production environments:

1. Use HTTPS URLs in configuration
2. Change default passwords
3. Enable audit logging
4. Use environment-specific configurations
5. Consider running MCP server in Docker

Support

If you encounter issues:

1. Check the MCP server logs
2. Verify platform service health
3. Review the configuration syntax
4. Check network connectivity
5. Create an issue in the repository