Model Context Protocol (MCP)

Response includes:

• Agent's response content
• Optional reasoning from the agent
• chat_id in metadata (when maintaining state)

3. clear_chat

Explicitly end a conversation and clear its history.

{
  "chat_id": "chat_1234567890_abc"
}

Setup Instructions

1. Generate OAuth Credentials

First, create OAuth credentials in Brightsy:

1. Log into your Brightsy account
2. Navigate to Settings → OAuth Applications
3. Click New Application
4. Fill in the details:
   • Name: "Claude Desktop" (or your application name)
   • Redirect URIs: Leave default for desktop applications
   • Scopes: Select brightsy:api
5. Save and copy your Client ID

Note: API Keys can also be created in Automations → API Keys for programmatic access, but OAuth is recommended for MCP integrations.

2. Configure Your MCP Client

For Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

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

Note: The mcp-remote tool proxies the HTTP streaming connection and handles OAuth 2.1 authentication with auto-discovery. The server automatically provides the authorization endpoints, so no manual OAuth configuration is needed. It will automatically open your browser for authorization when needed.

For Cursor

Cursor's configuration file is located at:

macOS/Linux: ~/.cursor/mcp.json Windows: %USERPROFILE%\.cursor\mcp.json

Add the same configuration as Claude Desktop above.

Note: As of Cursor 0.48.0+, direct HTTP connections are supported for unauthenticated servers. However, since Brightsy uses OAuth authentication, you still need to use mcp-remote to handle the OAuth flow.

3. Understanding mcp-remote

The mcp-remote tool is a proxy that converts HTTP streaming connections into the stdio protocol that desktop applications expect. It's necessary because:

• OAuth 2.1 Auto-Discovery: Automatically discovers authorization endpoints from the server
• OAuth Handling: Manages the complete OAuth 2.1 authorization flow
• Protocol Translation: Converts between HTTP streaming and stdio
• Token Management: Automatically refreshes tokens when needed
• Browser Integration: Opens your browser for authorization prompts

When mcp-remote runs for the first time, it will:

1. Query the MCP server for OAuth configuration (auto-discovery)
2. Open your default browser to the authorization page
3. Ask you to log in to Brightsy (if not already logged in)
4. Request permission to access your agents (scope: brightsy:api)
5. Store the access token locally for future use

Your sessions will remain authenticated until the token expires (typically 1 hour), after which mcp-remote will automatically prompt you to re-authorize.

Usage Examples

Example 1: List Available Agents

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

Example 2: Single-Turn Query

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...

Example 3: Multi-Turn Conversation

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. What metrics...

You: Focus on revenue by region
Claude: [calls chat tool with chat_id to continue conversation]
Claude: Based on the data, here's the revenue breakdown...

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

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

Authentication Issues

Problem: "Authentication required" error

Solutions:

• Ensure your OAuth application is active in Brightsy settings
• Verify the clientId matches your OAuth application
• Check that brightsy:api scope is included
• Try re-authorizing by removing and re-adding the server

Connection Issues

Problem: Can't connect to MCP server

Solutions:

• Verify the URL in your config is https://mcp.brightsy.ai/mcp
• Check your internet connection
• Ensure mcp-remote can be installed by running npx -y mcp-remote --version
• Look for errors in the MCP client logs
• Try running npx -y mcp-remote https://mcp.brightsy.ai/mcp manually to see error messages

mcp-remote Issues

Problem: mcp-remote not found or fails to start

Solutions:

• Ensure Node.js 18+ is installed: node --version
• Clear npx cache: npx clear-npx-cache
• Try installing globally: npm install -g mcp-remote
• Check that npx can access the network

Problem: OAuth browser window doesn't open

Solutions:

• The authorization URL will be printed to the console - copy and open manually
• Check that your default browser is set correctly
• Ensure pop-ups are not blocked
• Try setting the BROWSER environment variable to your browser path

Missing Agents

Problem: list_agents returns empty or missing agents

Solutions:

• Verify agents are enabled in your Brightsy account
• Check that your account has access to the agents
• Ensure agents have status "enabled"
• Refresh the OAuth token by re-authorizing

Session Expired

Problem: "Chat not found or expired" error

Solutions:

• Sessions expire after 1 hour of inactivity
• Start a new conversation without providing chat_id
• The MCP client should handle this automatically

Security & Privacy

• OAuth 2.0: Industry-standard authentication
• Token Expiration: Access tokens automatically expire
• User Isolation: Complete separation between users
• Encrypted Transit: All communication over HTTPS
• No Data Retention: Chat history expires automatically

Performance

• Redis Caching: Fast retrieval of conversation history
• Sliding Expiration: Efficient memory usage
• Auto-Cleanup: No manual maintenance required
• Scalable: Works across multiple server instances

API Rate Limits

The MCP server follows Brightsy's standard API rate limits:

• 100 requests per minute per user
• 1000 requests per hour per user
• Rate limits are shared across all API access methods

Support

For additional help:

• Join our Community Discord
• Email support: support@brightsy.ai
• Check API Status

Migration from Legacy CLI

If you were using the legacy brightsy-mcp CLI package:

Old configuration:

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

New configuration:

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

Benefits of the new approach:

• OAuth 2.1 with Auto-Discovery: More secure than API keys, automatic endpoint configuration
• Access All Agents: Not limited to a single agent
• Redis Session Management: Persistent chat history with automatic expiration
• Automatic Token Refresh: mcp-remote handles token lifecycle
• Multi-Turn Conversations: Maintain conversation context across messages
• Server-Side Updates: No need to update CLI tools
• User Isolation: Each user's conversations are private and isolated