# Sisense MCP Server

A Model Context Protocol (MCP) server that provides integration with Sisense analytics platform. This server enables LLMs to interact with Sisense data models and create charts programmatically.

## Features

- **Transport**: Streamable HTTP (`streamable-http`) for HTTP-based MCP clients (for example Claude Desktop, Cursor)
- **MCP tools** (three by default; optional fourth when enabled):
  - `getDataSources`: Retrieve Sisense data sources (or data models)
  - `getDataSourceFields`: List all available fields for a specific data source
  - `buildChart`: Build charts from natural language prompts
  - `buildQuery` (optional): Run analytics queries when `TOOL_BUILD_QUERY_ENABLED` / `toolBuildQueryEnabled` is enabled
- **MCP Apps**: When used in MCP Apps–capable clients (for example Claude), `buildChart` exposes an interactive View that renders the chart in an iframe within the app.
- **Per-session authentication**: Sisense credentials via URL parameters and/or server environment variables
- **TypeScript**: Full type safety and modern ESM support
- **Lightweight**: Pure Node.js HTTP server, no heavy frameworks
- **Fast**: Optimized for Bun runtime, also runs on Node.js

## Documentation

- [Quick start](docs/guides/quickstart.md) — clone, `.env`, run, MCP client setup
- [Configuration](docs/guides/configuration.md) — credentials, tunneling, feature flags, URL examples
- [FAQ](docs/guides/faq.md) — common questions and troubleshooting
- [Usage examples](docs/guides/usage-examples.md) — prompts and workflows

## Prerequisites

- **Node.js >= 18.0.0** (required for local development and `npm`)
- **Bun** for running project scripts (`dev`, `build`, `start`, tests): the `bun` package is a **devDependency**, so after `npm install` or `bun install` the Bun binary is available under `node_modules/.bin`—a global Bun install is not required. A global [Bun](https://bun.sh) install is optional.
- Sisense instance with API access
- Sisense API token
- **Cloud-Linked Features** enabled on your Sisense instance (and an LLM provider configured if using Bring Your Own Key (BYOK)). Required for natural-language tools such as `buildChart` and `buildQuery`. See [Generative AI (Cloud-Linked Features)](https://docs.sisense.com/main/SisenseLinux/genai.htm). This is separate from your MCP client's LLM (e.g. Claude in Cursor).
- Playwright Chromium (installed automatically by `bun install` / `npm install` via `postinstall`)

## Installation

```bash
bun install
# or
npm install
```

## Usage

Start the server:

```bash
# Development mode (hot reload)
bun run dev
# or
npm run dev

# Production mode
bun run build && bun run start
# or
npm run build && npm run start
```

Sessions are in-memory — chart state is lost if the server restarts.

The server prints something like the following (port defaults to **3001**, or `PORT` if set):

```text
Sisense MCP Server running on http://localhost:3001

Connect with:
  http://localhost:3001/mcp?sisenseUrl=<SISENSE_URL>&sisenseToken=<SISENSE_TOKEN>
  Or set SISENSE_URL and SISENSE_TOKEN in the environment and use http://localhost:3001/mcp

Optional feature-flag query params (override env vars per connection):
  mcpAppEnabled=true|false, toolBuildQueryEnabled=true|false, toolBuildChartNarrativeEnabled=true|false

Endpoints:
  Health: http://localhost:3001/health
  Screenshots: http://localhost:3001/screenshots/
```

### Connecting your MCP client

Use an MCP **streamable HTTP** URL. For Cursor, Claude Desktop, and similar clients, add a server entry with the MCP path (not a shell command such as `bun run dev` or `npm run dev`).

If `SISENSE_URL` and `SISENSE_TOKEN` are set in the **server** environment (for example in `.env` loaded by the process that runs `bun run dev` or `npm run dev`), the client URL does not need to include credentials:

```json
{
  "mcpServers": {
    "sisense-analytics": {
      "url": "http://localhost:3001/mcp"
    }
  }
}
```

**Note:** Depending on your network or client environment, the localhost HTTP setup may not connect. In those cases, you will need to expose your local server publicly via HTTPS using a proxy service such as [ngrok](https://ngrok.com/). Point the client at your HTTPS tunnel URL with the same `/mcp` path (and query parameters if you are not using server env credentials).

**Credentials:** If you do not use server env vars, put `sisenseUrl` and `sisenseToken` on the MCP URL as query parameters (URL params take precedence over env when both are present). Always percent-encode each value — see [Configuration: URL encoding](docs/guides/configuration.md#url-encoding-query-params) for details and examples.

Alternative connection patterns (placeholders only; use encoded values for real credentials):

```text
http://localhost:3001/mcp?sisenseUrl=https://your-instance.sisense.com&sisenseToken=your-api-token
```

With `SISENSE_URL` and `SISENSE_TOKEN` in the server environment only:

```text
http://localhost:3001/mcp
```

Behind a public HTTPS tunnel (example):

```text
https://your-ngrok-url.ngrok-free.app/mcp?sisenseUrl=https://your-instance.sisense.com&sisenseToken=your-api-token
```

### Claude (claude.ai and Desktop): Sisense CORS for interactive charts

In MCP App mode (the default), Anthropic Claude renders charts inside the MCP content UI—on **claude.ai** or **Claude Desktop**. The browser loads your Sisense instance from origins under `*.claudemcpcontent.com`, so Sisense must allow those origins or the widget fails with a network or CORS error.

In your Sisense instance, go to **Admin** → **Security Settings** → **CORS Allowed Origins** and add:

`https://*.claudemcpcontent.com`

Use this **subdomain wildcard** form. A single origin such as `https://claudemcpcontent.com` (no `*.`) may not match the actual frame origins and charts can still fail to load.

More context: [FAQ: Claude MCP App charts and CORS](docs/guides/faq.md#claude-mcp-app-charts-and-network-or-cors-errors).

## Configuration

| Parameter      | Description                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `sisenseUrl`   | Full URL to your Sisense instance (e.g., `https://instance.sisense.com`). In the query string, pass the value **percent-encoded**.              |
| `sisenseToken` | Sisense API authentication token. In the query string, pass the value **percent-encoded** (required if the token contains `&`, `=`, `+`, etc.). |
| `PORT`         | (Optional) Server port, defaults to 3001                                                                                                        |

The server automatically derives its public base URL from request headers, so it works correctly behind proxies like ngrok. For how to build encoded MCP URLs, see [URL encoding for query parameters](docs/guides/configuration.md#url-encoding-query-params).

### Optional feature-flag query parameters

Defaults suit most setups; change flags when you need a specific client behavior. For **when to use each flag**, copy-paste URL patterns, and env vs query string, see [docs/guides/configuration.md](docs/guides/configuration.md).

These query params override the corresponding env vars on a per-connection basis. Accepted values: `true`, `false`, `1`, `0` (case-insensitive).

| Query parameter                  | Env var equivalent                   | Default | Description                                                                                                              |
| -------------------------------- | ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `mcpAppEnabled`                  | `MCP_APP_ENABLED`                    | `true`  | Renders the chart in an interactive app UI (supported in Claude); set to `false` for tool mode (image/screenshot output) |
| `toolBuildQueryEnabled`          | `TOOL_BUILD_QUERY_ENABLED`           | `false` | Enable the `buildQuery` tool for executing analytics queries                                                             |
| `toolBuildChartNarrativeEnabled` | `TOOL_BUILD_CHART_NARRATIVE_ENABLED` | `true`  | Include NLG narrative/insights in the build chart tool response                                                          |

Example URL with all three overrides (encode `sisenseUrl` and `sisenseToken` values when they are not simple alphanumeric placeholders):

```text
http://localhost:3001/mcp?sisenseUrl=https://your-instance.sisense.com&sisenseToken=your-api-token&mcpAppEnabled=false&toolBuildQueryEnabled=true&toolBuildChartNarrativeEnabled=false
```

## Development

```bash
# Run server in development mode with hot reload
bun run dev
# or npm run dev

# Build the project (View + server)
bun run build
# or npm run build

# Build only the analytics View (dist/view.html)
bun run build:view
# or npm run build:view

# Run tests
bun test
# or npm test (same as npm run test)

# Type checking
bun run type-check
# or npm run type-check

# Lint
bun run lint
# or npm run lint
```

## Security Considerations

⚠️ NEVER commit credentials to version control

⚠️ Use secret managers or vaults - NOT environment variables in production

⚠️ NEVER bind to 0.0.0.0 in production - use 127.0.0.1 or Unix socket

⚠️ Recommended: Use dev or staging Sisense when you have them. Autonomous AI clients can issue many API calls, and prompts can be ambiguous. Non-production reduces the impact of mistakes and surprises.

⚠️ Enable authentication - never run without auth

⚠️ Approve EVERY tool call - review all parameters before execution

⚠️ Create dedicated Sisense service account with minimum required permissions

⚠️ Rotate credentials regularly (every 90 days recommended)