Brightsy MCP server

The Brightsy MCP Server connects to a Brightsy AI agent using the Model Context Protocol. It acts as a middleware that allows you to interact with Brightsy AI agents through a standardized interface.

Installation

To install the Brightsy MCP Server, run the following command:

npm install

Starting the Server

You can start the server using different approaches:

Using Named Arguments

npm start -- --agent-id=<your-agent-id> --api-key=<your-api-key>

Using Positional Arguments

npm start -- <your-agent-id> <your-api-key> [tool-name] [message]

With an Initial Message

You can provide an initial message to be sent to the agent:

npm start -- --agent-id=<your-agent-id> --api-key=<your-api-key> --message="Hello, agent!"

Configuration Options

Customizing the Tool Name

By default, the MCP server registers a tool named "brightsy". There are multiple ways to customize this name:

Using the Command Line Argument

npm start -- --agent-id=<your-agent-id> --api-key=<your-api-key> --tool-name=<custom-tool-name>

As a Positional Argument

npm start -- <your-agent-id> <your-api-key> <custom-tool-name>

Using Environment Variables

export BRIGHTSY_TOOL_NAME=custom-tool-name
npm start -- --agent-id=<your-agent-id> --api-key=<your-api-key>

Environment Variables

The server can be configured using these environment variables:

• BRIGHTSY_AGENT_ID: Your agent ID
• BRIGHTSY_API_KEY: Your API key
• BRIGHTSY_TOOL_NAME: Custom tool name (default: "brightsy")

Testing the Agent

Setting Up Test Environment

Before running tests, configure your environment:

export AGENT_ID=your-agent-id
export API_KEY=your-api-key
export TOOL_NAME=custom-tool-name  # Optional

Or use command-line arguments:

# Named arguments
npm run test:cli -- --agent-id=your-agent-id --api-key=your-api-key --tool-name=custom-tool-name

# Positional arguments
npm run test:cli -- your-agent-id your-api-key custom-tool-name

Running Tests

Run all tests:

npm test

Run specific tests:

# Test using CLI
npm run test:cli

# Test using direct MCP protocol
npm run test:direct

Using the Tool

The MCP server registers a tool that forwards requests to a Brightsy AI agent. Here's how to use it in an MCP client:

// Using the default tool name
const response = await client.callTool("brightsy", {
  messages: [
    {
      role: "user",
      content: "Hello, can you help me with a simple task?"
    }
  ]
});

// Using a custom tool name
const response = await client.callTool("custom-tool-name", {
  messages: [
    {
      role: "user",
      content: "Hello, can you help me with a simple task?"
    }
  ]
});

The response will contain the agent's reply in the content field.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.