Model Context Protocol (MCP)

3. Web MCP Server (HTTP Streaming)

Best for: Remote AI agent access without local installation.

• HTTP Transport: Web-based MCP server using HTTP streaming
• OAuth 2.1: Secure authentication with auto-discovery
• Agent-Focused: Optimized for AI agent conversations
• mcp-remote Proxy: Required client proxy for stdio-to-HTTP translation

Brightsy Desktop MCP (Recommended)

Brightsy Desktop provides the most comprehensive MCP experience with the Brightsy MCP server bundled and full client capabilities. The desktop app includes both MCP client functionality (to connect to servers) and the Brightsy MCP server itself (to provide tools), making setup seamless.

Installation & Setup

1. Install Brightsy Desktop: Download and install from brightsy.ai/download
2. Log in: Open Brightsy Desktop and authenticate with your account
3. Configure AI Tool: The Brightsy MCP server is bundled with the desktop app - just configure your AI tool to connect to it

Using Desktop with MCP Servers

The desktop app includes the Brightsy MCP server as a bundled dependency, providing seamless access to both local development tools and cloud platform features.

Option A: Desktop MCP Server (Recommended)

The Brightsy MCP server is pre-installed with the desktop app and automatically reads allowed directories from your desktop configuration. Simply configure your AI tools to connect to it:

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp"
    }
  }
}

Advanced Cursor Configuration (optional - overrides auto-detection):

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp",
      "env": {
        "BRIGHTSY_ALLOWED_DIRS": "/Users/username/projects,/Users/username/workspace",
        "BRIGHTSY_API_KEY": "bsy_your_api_key",  // Alternative to OAuth
        "BRIGHTSY_ACCOUNT_ID": "your_account_id"   // Required with API key
      },
      "timeout": 30000,
      "initializationOptions": {}
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp"
    }
  }
}

Option B: Standalone MCP Server

For advanced use cases, you can also run the MCP server independently:

# Install globally (if not using desktop app)
npm install -g @brightsy/mcp-server

# Run standalone
brightsy-mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp"
    }
  }
}

Desktop MCP Client Features

• MCP Server Discovery: Automatically discovers and connects to configured MCP servers
• Workspace Integration: Passes workspace context to MCP servers for file and terminal operations
• Authentication Sharing: Uses desktop app credentials when connecting to authenticated MCP servers
• Multi-Server Support: Can connect to multiple MCP servers simultaneously
• Tool Management: Loads and manages tools from all connected MCP servers
• Error Handling: Provides user-friendly error messages for MCP server issues

Note: The Brightsy MCP server is bundled with the desktop app, but you still need to configure your AI tools to connect to it. The desktop app provides both client and server capabilities for a complete MCP experience.

Standalone MCP Server

For standalone deployments or custom configurations, use the @brightsy/mcp-server npm package.

Installation

npm install -g @brightsy/mcp-server

Configuration

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp",
      "env": {
        "BRIGHTSY_ALLOWED_DIRS": "/path/to/your/workspace"
      }
    }
  }
}

Aider:

aider --mcp brightsy-mcp

Authentication

The standalone server supports multiple authentication methods:

• OAuth 2.1 with PKCE: Automatic browser-based authentication
• API Key: For server-to-server scenarios
• CLI Login: Use brightsy login to authenticate

Environment Variables

• BRIGHTSY_ALLOWED_DIRS: Comma-separated paths for local file access (defaults to current directory)
• BRIGHTSY_API_KEY: API key for authentication (alternative to OAuth)
• BRIGHTSY_ACCOUNT_ID: Account ID when using API key authentication

Complete Cursor Configuration Guide

Cursor's .cursor/mcp.json supports comprehensive configuration options:

Basic Setup

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp"
    }
  }
}

Full Configuration with Environment Variables

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp",
      "env": {
        "BRIGHTSY_ALLOWED_DIRS": "/Users/username/projects,/Users/username/workspace",
        "BRIGHTSY_API_KEY": "bsy_your_api_key",
        "BRIGHTSY_ACCOUNT_ID": "your_account_id",
        "BRIGHTSY_ENDPOINT": "https://custom.brightsy.ai"
      },
      "timeout": 30000
    }
  }
}

Advanced Configuration Options

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp",
      "args": ["--verbose", "--debug"],
      "env": {
        "BRIGHTSY_ALLOWED_DIRS": "/path/to/workspace",
        "NODE_ENV": "development"
      },
      "timeout": 60000,
      "initializationOptions": {
        "logLevel": "debug",
        "customConfig": {}
      }
    }
  }
}

Multiple MCP Servers

{
  "mcpServers": {
    "brightsy-local": {
      "command": "brightsy-mcp",
      "env": {
        "BRIGHTSY_ALLOWED_DIRS": "/local/workspace"
      }
    },
    "brightsy-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.brightsy.ai/mcp"]
    }
  }
}

Environment Variables Reference

Note: When using Brightsy Desktop, most configuration is automatically detected from the desktop app's settings and shared config file. Manual environment variables are only needed for advanced customization or standalone MCP server usage.

Configuration Properties

Web MCP Server

Available Tools by Category

Local Development Tools (No Authentication Required)

Filesystem Operations:

• local_read_file: Read file contents from allowed directories
• local_write_file: Write or update files in allowed directories
• local_list_files: List directory contents
• local_search_files: Search for files by pattern
• local_grep: Search file contents with regex

Terminal & Process Management:

• local_run_command: Execute shell commands with timeout/buffer options
• start_managed_process: Start long-running processes with monitoring
• discover_cli_tools: Find npm scripts, Makefile targets, Docker Compose services

System Information:

• brightsy_server_info: Get server version and status information

Cloud Platform Tools (Authentication Required)

Agent Management:

• list_agents: List all available AI agents
• get_agent: Get detailed agent configuration
• create_agent: Create new AI agent
• update_agent: Modify existing agent
• delete_agent: Remove agent
• chat: Chat with an agent (supports multi-turn conversations)

Direct AI Model Access:

• list_models: List available AI models with capabilities
• complete: Direct model completion without agent wrapper

Content Management (Records & CMS):

• get_record_types: List all record type schemas
• get_record_type: Get specific record type schema
• create_record_type: Create new record type
• update_record_type: Modify record type
• delete_record_type: Remove record type
• list_records: Query records with filtering and pagination
• get_record: Get single record
• create_record: Create new record
• update_record: Modify record
• delete_record: Remove record
• publish_record: Publish draft record to live

Sites & Page Builder:

• list_sites: List all sites
• get_site: Get site details
• create_site: Create new site
• update_site: Modify site
• delete_site: Remove site
• list_pages: List pages in a site
• get_page: Get page details
• create_page: Create new page
• update_page: Modify page
• delete_page: Remove page
• get_site_theme: Get site theme configuration
• update_site_theme: Modify theme settings

Component Libraries:

• list_libs: List component libraries
• get_lib: Get library details
• create_lib: Create new library
• update_lib: Modify library
• delete_lib: Remove library
• deploy_lib: Deploy library to environment
• list_page_types: List page types in a site
• create_page_type: Create page type
• assign_lib_to_page_type: Assign library to page type

File Management:

• list_files: List files in storage
• upload_file: Upload file to storage
• get_upload_url: Get signed upload URL
• delete_file: Remove file
• get_signed_url: Get signed download URL

Automation:

• list_scenarios: List automation scenarios
• get_scenario: Get scenario details
• create_scenario: Create new scenario
• update_scenario: Modify scenario
• delete_scenario: Remove scenario
• trigger_scenario: Execute scenario manually
• list_schedules: List scheduled tasks
• get_schedule: Get schedule details
• create_schedule: Create new schedule
• update_schedule: Modify schedule
• delete_schedule: Remove schedule

API Management:

• list_apikeys: List API keys
• create_apikey: Create new API key
• delete_apikey: Remove API key
• list_webhooks: List webhooks
• create_webhook: Create new webhook
• update_webhook: Modify webhook
• delete_webhook: Remove webhook

Chat Management Tools

• clear_chat: End conversation and clear history
• get_chat_history: Retrieve conversation history (when supported)

AI Image Tools

• analyze_image: Analyze image content
• generate_image: Generate new images
• suggest_image_edits: Get image editing suggestions

Setup Instructions

Choose the MCP integration that best fits your needs:

Option 1: Brightsy Desktop (Easiest)

1. Download and install Brightsy Desktop from brightsy.ai/download
2. Log in to Brightsy Desktop with your account
3. Configure your AI tool to use the bundled MCP server:

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-desktop-mcp"
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-desktop-mcp"
    }
  }
}

That's it! The MCP server will automatically use your Brightsy Desktop authentication and provide access to all local and cloud tools.

Option 2: Standalone MCP Server

1. Install the MCP server:

npm install -g @brightsy/mcp-server

2. Authenticate (choose one method):

   • OAuth: Run brightsy-mcp and follow browser authentication
   • CLI: Run brightsy login first
   • API Key: Set BRIGHTSY_API_KEY and BRIGHTSY_ACCOUNT_ID environment variables

3. Configure your AI tool:

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp",
      "env": {
        "BRIGHTSY_ALLOWED_DIRS": "/path/to/your/workspace"
      }
    }
  }
}

Aider:

aider --mcp brightsy-mcp

Option 3: Web MCP Server (Legacy)

For remote access or when you can't install local tools:

1. Create OAuth credentials in Brightsy:

   • Go to Settings → OAuth Applications
   • Create new application with brightsy:api scope

2. Configure your AI tool:

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "brightsy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.brightsy.ai/mcp"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "brightsy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.brightsy.ai/mcp"
      ]
    }
  }
}

The mcp-remote tool handles OAuth authentication and protocol translation automatically.

Usage Examples

Desktop MCP Examples (Recommended)

With Brightsy Desktop, you get access to both local development tools and cloud platform features:

You: Read the package.json file in my current project
Claude: [calls local_read_file tool]
Claude: Here's your package.json:
{
  "name": "my-project",
  "version": "1.0.0",
  ...
}

You: Run npm test in my project
Claude: [calls local_run_command tool]
Claude: Running npm test...
✓ All tests passed

You: Create a new blog post about React 19
Claude: [calls create_record tool with record_type='blog-post']
Claude: Created blog post with ID: post-123
Title: "Exploring React 19 Features"
Content: "React 19 introduces..."

Cloud-Only Examples

For web MCP server or when focused on platform features:

You: List all my Brightsy agents
Claude: [calls list_agents tool]
Claude: You have 3 agents available:
1. Customer Support Agent (agent-123) - Handles customer inquiries
2. Data Analysis Agent (agent-456) - Performs data analysis tasks
3. Content Writer Agent (agent-789) - Creates marketing content

You: Ask my Customer Support Agent about order #12345
Claude: [calls chat tool with agent_id and message]
Claude: The agent says: Order #12345 was shipped on Jan 15th and is expected to arrive by Jan 20th...

You: Start a conversation with my Data Analysis Agent about Q4 sales
Claude: [calls chat tool, receives chat_id in response]
Claude: The agent says: I'd be happy to analyze Q4 sales data. What specific metrics are you interested in?

You: Focus on revenue by region
Claude: [calls chat tool with chat_id to continue conversation]
Claude: Based on the Q4 data, here are the revenue figures by region:
- North America: $2.4M
- Europe: $1.8M
- Asia Pacific: $1.2M

You: End this conversation
Claude: [calls clear_chat tool]
Claude: Conversation ended and history cleared.

SDK Integration Examples

MCP tools complement the BrightsyClient SDK for programmatic access:

import { BrightsyClient } from '@brightsy/client';

const client = new BrightsyClient({
  api_key: 'bsy_...',
  account_id: 'account-uuid'
});

// MCP can help discover available record types
const types = await client.cma().listRecordTypes();

// Then work with specific types
const posts = await client.cda()
  .recordType('blog-post')
  .where('status', 'eq', 'published')
  .get();

CLI Integration Examples

The Brightsy CLI works alongside MCP for development workflows:

# MCP can help with CLI operations
brightsy create my-component-library
cd my-component-library
brightsy connect  # MCP helps select site/library
brightsy push --dev  # Register with MCP-configured environments

BrightsyClient SDK Integration

MCP tools provide AI-assisted access to Brightsy's TypeScript/JavaScript SDK, making it easier to discover and use platform features:

Installation

npm install @brightsy/client

Basic Usage

import { BrightsyClient } from '@brightsy/client';

const client = new BrightsyClient({
  api_key: 'bsy_...',
  account_id: 'account-uuid'
});

// MCP tools can help you discover available APIs
// Use list_agents, get_record_types, etc. through MCP

// Then use the SDK programmatically
const agents = await client.agents().list();
const records = await client.cda()
  .recordType('blog-post')
  .where('published', 'eq', true)
  .get();

SDK Features Accessible via MCP

• Content Management: CMA/CDA/CPA APIs for draft/published/preview content
• Agent Management: Create, chat, and manage AI agents
• File Operations: Upload, download, and manage files with signed URLs
• Site Building: Visual page builder and component libraries
• Automation: Scenarios, schedules, and webhooks
• Direct AI: Model access without agent wrappers

Brightsy CLI Integration

The Brightsy CLI (@brightsy/cli) provides command-line access to platform features and works seamlessly with MCP:

Installation

npm install -g @brightsy/cli

Authentication

brightsy login  # OAuth authentication
brightsy logout
brightsy whoami  # Check current account

Key Commands

# Agent interactions (similar to MCP chat tools)
brightsy chat "Hello!"                    # Chat with default agent
brightsy chat --agent <id> "Message"      # Chat with specific agent
brightsy chat --model gpt_5_2 "Query"     # Direct model completion
brightsy agents                           # List available agents

# Content management
brightsy records list blog-post           # List records
brightsy records create blog-post         # Create record
brightsy record-types list                # List schemas

# Component development
brightsy create my-components             # Scaffold library
brightsy connect                          # Link to site
brightsy push --dev                       # Deploy to dev
brightsy push                             # Deploy to production

MCP + CLI Workflow

MCP and CLI complement each other:

1. Use MCP for AI-assisted discovery and complex operations
2. Use CLI for repetitive tasks and scripting
3. Both share the same authentication and account context

Example workflow:

# MCP discovers available record types
# MCP: "You have 'blog-post' and 'product' record types"

# CLI creates content based on MCP guidance
brightsy records create blog-post --data '{"title":"New Post","content":"..."}'

# MCP helps with deployment
# MCP: "Your component library is ready. Run 'brightsy push' to deploy"

Chat Session Management

Stateless Mode (Default)

By default, each chat is independent:

• No chat_id is provided
• Agent has no memory of previous messages
• Best for one-off queries

Stateful Mode

To maintain conversation history:

• Provide a chat_id to continue a conversation
• The MCP client automatically manages the chat_id
• Sessions expire after 1 hour of inactivity
• Active sessions refresh their expiration on every message

Session Isolation

• Each user's chats are completely isolated
• Team members can't access each other's conversations
• Redis provides persistent storage across server restarts

Advanced Features

UI Tool Auto-Handling

When agents use UI tools (like show_buttons or present_content), the MCP server automatically:

1. Detects the UI tool call
2. Generates a mock response
3. Continues the conversation seamlessly

This allows agents designed for web interfaces to work through MCP without modification.

Sliding Expiration

Chat sessions use Redis with sliding expiration:

• Sessions expire after 1 hour of inactivity
• Every message resets the timer
• Active conversations never expire
• Old sessions auto-cleanup

Concurrent Conversations

You can maintain multiple simultaneous conversations:

• Each has a unique chat_id
• Switch between conversations seamlessly
• Clear individual conversations when done

Troubleshooting

Brightsy Desktop Issues

Problem: "brightsy-desktop-mcp command not found"

Solutions:

• Ensure Brightsy Desktop is installed and running
• Restart your AI tool (Cursor/Claude Desktop) after installing Desktop
• Check that Brightsy Desktop is logged in to your account
• Verify the Desktop app is in your system's PATH

Problem: Desktop MCP server not starting

Solutions:

• Restart Brightsy Desktop
• Check Desktop app logs for errors
• Ensure your account has active subscription
• Try logging out and back in to Desktop app

Standalone MCP Server Issues

Problem: "brightsy-mcp command not found"

Solutions:

• Install globally: npm install -g @brightsy/mcp-server
• Check Node.js version: node --version (requires 18+)
• Clear npm cache: npm cache clean --force
• Try running with npx: npx @brightsy/mcp-server

Problem: Authentication fails with standalone server

Solutions:

• Run brightsy login first if using CLI authentication
• Check BRIGHTSY_API_KEY and BRIGHTSY_ACCOUNT_ID environment variables
• For OAuth: ensure browser can open for authentication
• Verify your account has MCP access enabled

Web MCP Server Issues

Problem: "mcp-remote not found"

Solutions:

• Ensure Node.js 18+ is installed
• Clear npx cache: npx clear-npx-cache
• Install globally: npm install -g mcp-remote
• Check network connectivity

Problem: OAuth authorization fails

Solutions:

• Verify OAuth application exists in Brightsy settings
• Check that brightsy:api scope is granted
• Ensure redirect URIs are configured correctly
• Try re-creating the OAuth application

General MCP Issues

Problem: Tools not appearing in AI client

Solutions:

• Restart your AI tool (Cursor/Claude Desktop)
• Check MCP configuration file syntax
• Verify server command is correct and executable
• Look for error messages in AI tool's MCP logs

MCP Configuration Issues

Problem: "I installed Brightsy Desktop but MCP tools aren't available"

Solutions:

• Ensure Brightsy Desktop is logged in and has OAuth credentials
• Check that your .cursor/mcp.json or claude_desktop_config.json is configured correctly
• Restart your AI tool (Cursor/Claude Desktop) after configuration changes
• Verify the MCP server is accessible by running brightsy-mcp in terminal

Problem: "MCP server not found" error

Solutions:

• Brightsy Desktop includes the MCP server, but you may need to install it globally for standalone use
• Run npm install -g @brightsy/mcp-server if using MCP server outside of desktop app
• Check that brightsy-mcp command is available in your PATH
• For desktop app, the MCP server should be available automatically

Problem: "Tool execution failed" errors

Solutions:

• Check network connectivity for cloud tools
• Verify authentication is still valid
• Ensure your account has access to requested resources
• Check rate limits (100 requests/minute, 1000/hour)

Problem: Local file access denied

Solutions:

• Set BRIGHTSY_ALLOWED_DIRS environment variable
• Run AI tool from project directory (defaults to cwd)
• Check file permissions on target directories
• For Desktop MCP: ensure Desktop has access to requested paths

Platform-Specific Issues

macOS:

• Check ~/Library/Application Support/Claude/claude_desktop_config.json
• Verify Brightsy Desktop is in /Applications
• Check system PATH for Brightsy commands

Windows:

• Check %APPDATA%\Claude\claude_desktop_config.json
• Verify Brightsy Desktop installation path
• Check Windows PATH environment variable

Linux:

• Check ~/.config/Claude/claude_desktop_config.json
• Verify Node.js and npm are installed
• Check executable permissions on MCP server

Security & Privacy

Authentication Methods

• OAuth 2.1 with PKCE: Industry-standard for user-authorized access
• API Keys: For server-to-server scenarios
• Token Auto-Rotation: Automatic refresh without user intervention
• User Isolation: Complete separation between accounts and conversations

Data Protection

• Encrypted Transit: All communication over HTTPS/TLS 1.3
• At-Rest Encryption: Sensitive data encrypted in database
• Chat Expiration: Automatic cleanup after 1 hour of inactivity
• File Security: Signed URLs with expiration for secure access
• Audit Logging: Comprehensive activity tracking

Local Tool Security

• Path Restrictions: Configurable allowed directories for file access
• Command Sandboxing: Terminal commands run in controlled environment
• Process Limits: Timeout and buffer limits on command execution
• Permission Checks: Validate access before operations

Performance & Reliability

Desktop MCP Performance

• Native Compilation: Optimized for low latency
• Local Caching: Fast access to frequently used data
• Background Processing: Non-blocking tool execution
• Memory Management: Efficient resource usage

Cloud MCP Performance

• Redis Caching: Fast retrieval of conversation history
• CDN Integration: Global edge network for low latency
• Auto-Scaling: Dynamic server allocation based on load
• Connection Pooling: Efficient database connection management

Reliability Features

• Automatic Failover: Redundant server instances
• Circuit Breakers: Protect against cascading failures
• Graceful Degradation: Continue operating during partial outages
• Health Monitoring: Real-time system status tracking

API Rate Limits & Quotas

MCP Tool Limits

• 100 requests per minute per user across all MCP tools
• 1000 requests per hour per user
• 50 concurrent conversations maximum per user
• Rate limits shared across Desktop, Standalone, and Web MCP

Platform Quotas

• File Storage: Account-based storage limits
• API Keys: Maximum 50 active keys per account
• Webhooks: 100 active webhooks per account
• Component Libraries: Unlimited libraries, size limits per deployment

AI Model Limits

• Direct Model Access: Subject to model provider rate limits
• Agent Usage: Account-based usage quotas
• Image Generation: Monthly quota based on subscription tier

Documentation Resources

The MCP server provides comprehensive documentation through MCP resources:

• brightsy://docs/overview - Platform overview and concepts
• brightsy://docs/agents - AI agents guide
• brightsy://docs/records - Content management guide
• brightsy://docs/sites - Visual page builder guide
• brightsy://docs/models - Direct AI model access
• brightsy://docs/client - BrightsyClient SDK reference
• brightsy://docs/cli - CLI command reference
• brightsy://docs/component-library-guide - Component development
• brightsy://docs/theme - Theme system guide
• And 10+ additional specialized guides

Support & Community

Getting Help

• Documentation: Comprehensive guides at docs.brightsy.ai
• Community Discord: Join discord.gg/brightsy for community support
• GitHub Issues: Report bugs and request features
• Email Support: support@brightsy.ai for account and billing issues

Status & Monitoring

• System Status: Check status.brightsy.ai for service health
• API Status: Real-time API availability monitoring
• MCP Health: Tool-specific status checking
• Incident History: Past incidents and resolution details

Professional Services

• Custom Integrations: MCP server customization
• Training & Consulting: Platform adoption assistance
• Enterprise Support: Priority response and dedicated support
• Migration Services: Legacy system migration assistance

Latest Features & Updates

Version 1.0+ Features

• 60+ MCP Tools: Comprehensive platform access including agents, CMS, sites, files, and automation
• Local Development Tools: Filesystem, terminal, and CLI discovery (no auth required)
• Component Library Support: Full integration with Brightsy's visual page builder
• Direct AI Model Access: Use any supported model without creating agents
• Advanced Content Management: CMA/CDA/CPA APIs with draft/published workflows
• Automation Integration: Scenarios, schedules, and webhook management
• Image AI Tools: Analysis, generation, and editing suggestions

BrightsyClient SDK v1.x

The TypeScript/JavaScript SDK provides programmatic access to all MCP-accessible features:

const client = new BrightsyClient({
  api_key: 'bsy_...',
  account_id: 'account-uuid'
});

// Full platform API access
const agents = await client.agents().list();
const records = await client.cma().recordType('blog-post').get();
const sites = await client.sites().list();

Brightsy CLI v1.x

Command-line interface with OAuth authentication and MCP integration:

brightsy login                    # OAuth authentication
brightsy chat "Hello agent!"      # Interactive chat
brightsy records list blog-post   # Content management
brightsy create my-components     # Component development
brightsy push                     # Deploy libraries

Migration Guide

From Legacy CLI to Modern MCP

Old approach (limited to single agent):

{
  "brightsy-old": {
    "command": "npx",
    "args": ["-y", "brightsy-mcp", "--agent-id=abc-123", "--api-key=..."]
  }
}

New approach (full platform access):

{
  "brightsy": {
    "command": "brightsy-desktop-mcp"
  }
}

From API Keys to OAuth

Migration benefits:

• Enhanced Security: OAuth 2.1 with PKCE instead of static API keys
• Auto-Discovery: Automatic endpoint configuration
• Token Rotation: Automatic refresh without manual intervention
• Granular Scopes: Precise permission control
• User Context: Access tied to authenticated user identity

From Web-Only to Desktop MCP

Upgrade path:

1. Install Brightsy Desktop
2. Log in to your account
3. Update MCP configuration to use brightsy-desktop-mcp
4. Get access to local development tools + cloud features

Benefits:

• Local File Access: Read/write project files
• Terminal Integration: Run commands in authenticated sessions
• Process Management: Monitor long-running tasks
• Zero Configuration: Works immediately after installation