Brightsy MCP Server

Standalone MCP server for Brightsy: local and cloud tools for Cursor, aider, claude-cli.

Installation

Standalone (npm):

npm install -g @brightsy/mcp-server

With Brightsy Desktop:
The MCP server is bundled with the desktop app. When you install Brightsy Desktop, you can run the server from the app's context or use the same config.

Configuration

Add to your AI tool's MCP config.

Cursor — hosted MCP (recommended) — OAuth, no global install. See docs/CURSOR_SETUP.md.

~/.cursor/mcp.json or .cursor/mcp.json:

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

mcp-remote bridges Cursor (stdio) to the hosted server and handles OAuth on first use.

Cursor — local stdio (filesystem/terminal tools, or local dev):

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

aider:

aider --mcp brightsy-mcp

Environment (optional):

• BRIGHTSY_ALLOWED_DIRS – Comma-separated paths for local file tools. Defaults to current working directory.
• BRIGHTSY_API_URL – API base URL (default: https://brightsy.ai). Set to http://localhost:3000 to use a local Brightsy web instance.
• BRIGHTSY_DOCS_BASE_URL – Optional. When set (e.g. https://brightsy.ai or http://localhost:3000), MCP documentation resources are loaded over HTTP from {base}/mcp-docs/v1/manifest.json and {base}/mcp-docs/v1/bodies/*.md. When unset, the brightsy-ai monorepo build loads docs from @kit/shared/docs (same as the web MCP); published installs use the bundled static/mcp-docs/v1/ tree produced by pnpm run generate-mcp-docs-static before publish.

Connecting to local Brightsy (localhost:3000):

1. Start the Brightsy web app locally (e.g. pnpm dev in apps/web).
2. In .cursor/mcp.json, add a server that passes the URL via env:

   "brightsy-local": {
     "command": "brightsy-mcp",
     "env": { "BRIGHTSY_API_URL": "http://localhost:3000" }
   }

3. Restart Cursor and pick the brightsy-local MCP server. On first use you’ll be prompted to log in; complete OAuth against your local instance.

Authentication

• With Desktop app: Log in via Brightsy Desktop; the MCP server uses the same tokens from ~/.brightsy/config.json.
• Standalone: Run brightsy-mcp and use a cloud tool (e.g. get_record_types); if not logged in, the server can open a browser for OAuth (when implemented) or you can log in via the Brightsy CLI (brightsy login).

Tools

Local (no auth required)

• Filesystem: local_read_file, local_write_file, local_list_files, local_search_files, local_grep
• Terminal: local_run_command (with timeout/max_buffer options)
• CLI Discovery: discover_cli_tools (finds npm scripts, Makefile targets, docker-compose services)
• Workspace: local_get_workspace_info (root + allowed directories)

Cloud (~40 tools via SDK proxy; hosted MCP has ~66, require login)

• Agent Management: Create, update, delete, and chat with AI agents
• Records & CMS: Full CRUD for record types and records
• Files: Storage management with signed URLs
• Automation: Scenarios, schedules, webhooks
• Direct AI: list_models, complete (direct model access)
• And more: See TOOLS.md for complete reference

Documentation Resources

The server exposes Markdown guides as MCP resources (URIs like brightsy://docs/overview, brightsy://docs/cli, brightsy://docs/client, etc.). In the monorepo, the source of truth is @kit/shared/docs; static/HTTP paths are used for published packages or when BRIGHTSY_DOCS_BASE_URL is set.

Meta

• brightsy_server_info – Server version and status

Two MCP-related implementations

Brightsy has two MCP-related surfaces: (1) this package is the MCP server (stdio) used by Cursor/aider/Desktop; (2) the web app provides agent (prompt) tools and acts as an MCP client to user-configured external servers. See docs/MCP_IMPLEMENTATIONS.md for how they differ and how to keep record tools (e.g. publish_record) in sync.

Development

From the brightsy-ai monorepo root, generate bundled docs (required once after clone or when packages/shared docs change), then build:

pnpm run generate-mcp-docs-static
pnpm --filter @brightsy/mcp-server build
pnpm --filter @brightsy/mcp-server start

Inside the monorepo you can also run pnpm --filter @brightsy/mcp-server sync-docs to regenerate static docs only.

Run from a project directory so process.cwd() (and, if set, BRIGHTSY_ALLOWED_DIRS) point at the right workspace.