MCP Server — Overview & Setup

The Brightly AI MCP Server gives AI agents typed access to your CRM data. Connect Claude Desktop, Cursor, Claude Code, or any MCP-compatible client to manage leads, book appointments, create tasks, and send messages — all through your existing API key.

Two Transport Modes

HTTP (Streamable HTTP)

For persistent AI agents and server-side integrations.

• Endpoint: https://api.brightlyai.app/mcp
• Auth: Authorization: Bearer brk_your_key on every request
• Sessions: Server returns mcp-session-id header after initialization. Include it on subsequent requests.
• TTL: Sessions expire after 30 minutes of inactivity
• Close: DELETE /mcp to end the session
• Capacity: Up to 1,000 concurrent sessions

Stdio (Local CLI)

For local development and desktop AI clients.

• Command: node mcp/stdio.js
• Config: Set BRIGHTLY_API_KEY and optionally BRIGHTLY_API_URL environment variables
• Proxying: The stdio binary calls the remote REST API — no local database needed

Setup: Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "brightly": {
      "command": "node",
      "args": ["/path/to/brightly-crm/mcp/stdio.js"],
      "env": {
        "BRIGHTLY_API_KEY": "brk_your_key_here"
      }
    }
  }
}

Setup: Claude Code

Add this to your project’s .mcp.json:

{
  "mcpServers": {
    "brightly": {
      "type": "http",
      "url": "https://api.brightlyai.app/mcp",
      "headers": {
        "Authorization": "Bearer brk_your_key_here"
      }
    }
  }
}

Setup: Cursor

In Cursor Settings > MCP Servers, add:

{
  "brightly": {
    "command": "node",
    "args": ["/path/to/brightly-crm/mcp/stdio.js"],
    "env": {
      "BRIGHTLY_API_KEY": "brk_your_key_here"
    }
  }
}

Authentication & Scopes

The MCP server uses the same API key authentication as the REST API. Scopes work identically:

• A key with empty scopes has full access to all tools
• A key with specific scopes can only use tools that match those scopes
• Scope denials return a text message (not a JSON error): "Permission denied: API key missing scope 'leads:read'"

See the Tool Reference for which scope each tool requires.

Rate Limits

MCP requests are rate-limited identically to REST API calls:

• 60 reads/min per API key
• 30 writes/min per API key