brightsy-logo-horz

Brightsy AI provides a native Model Context Protocol (MCP) server, enabling seamless integration with AI platforms like Claude Desktop, Cursor, and other MCP-compatible applications.

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI applications to connect to external data sources and tools. It provides a unified way for AI assistants to access your Brightsy agents, maintaining context and enabling powerful multi-turn conversations.

Brightsy MCP Server

The Brightsy MCP server is built directly into the platform and accessible via OAuth 2.1 authentication with auto-discovery. No additional installation or CLI tools are required - just configure mcp-remote to connect.

Features

OAuth 2.1 with Auto-Discovery: Secure authentication with automatic endpoint configuration
Multi-Turn Conversations: Maintain chat history with optional session management
Redis-Backed Storage: Persistent chat sessions with automatic expiration
User Isolation: Each user's conversations are completely isolated
Auto-Cleanup: Inactive chats expire after 1 hour of inactivity
Sliding Expiration: Active conversations never expire
UI Tool Support: Agents can use UI tools with automatic server-side handling
No Manual Configuration: mcp-remote automatically discovers OAuth endpoints

Available Tools

1. `list_agents`

Lists all agents you have access to in your account.

Agents are managed in the Agents section of the platform, where you can create, configure, and test AI assistants with custom prompts, tools, and models.

{
  "agents": [
    {
      "agent_id": "abc-123",
      "agent_name": "Customer Support Agent",
      "description": "Handles customer inquiries"
    }
  ]
}

2. `chat`

Chat with an agent. Supports both stateless (single-turn) and stateful (multi-turn) conversations.

Parameters:

agent_id (required): ID of the agent to chat with
message (required): Your message to the agent
chat_id (optional): ID to continue an existing conversation
system_context (optional): Additional context for the agent

Single-turn (stateless) example:

{
  "agent_id": "abc-123",
  "message": "What's the status of order #12345?"
}

Multi-turn (stateful) example:

{
  "agent_id": "abc-123",
  "message": "Tell me more about that",
  "chat_id": "chat_1234567890_abc"
}

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:

Log into your Brightsy account
Navigate to Settings → OAuth Applications
Click New Application
Fill in the details:
- Name: "Claude Desktop" (or your application name)
- Redirect URIs: Leave default for desktop applications
- Scopes: Select brightsy:api
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:

Query the MCP server for OAuth configuration (auto-discovery)
Open your default browser to the authorization page
Ask you to log in to Brightsy (if not already logged in)
Request permission to access your agents (scope: brightsy:api)
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:

Detects the UI tool call
Generates a mock response
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

Model Context Protocol (MCP)

Brightsy AI: Model Context Protocol Integration

What is MCP?

Brightsy MCP Server

Features

Available Tools

1. list_agents

2. chat

3. clear_chat

Setup Instructions

1. Generate OAuth Credentials

2. Configure Your MCP Client

For Claude Desktop

For Cursor

3. Understanding mcp-remote

Usage Examples

Example 1: List Available Agents

Example 2: Single-Turn Query

Example 3: Multi-Turn Conversation

Chat Session Management

Stateless Mode (Default)

Stateful Mode

Session Isolation

Advanced Features

UI Tool Auto-Handling

Sliding Expiration

Concurrent Conversations

Troubleshooting

Authentication Issues

Connection Issues

mcp-remote Issues

Missing Agents

Session Expired

Security & Privacy

Performance

API Rate Limits

Support

Migration from Legacy CLI

1. `list_agents`

2. `chat`

3. `clear_chat`