# MCP Server Setup

brightspaceR includes an MCP (Model Context Protocol) server that lets AI assistants like Claude query your Brightspace data using natural language. Instead of writing R code yourself, you describe what you want and the assistant discovers datasets, writes the analysis code, executes it, and returns the results – including interactive Chart.js visualisations.

This guide walks through installing and configuring the MCP server for Claude Desktop and Claude Code (CLI).

## Prerequisites

Before setting up the MCP server, make sure you have:

1. brightspaceR installed – either from GitHub or loaded from a local clone:

       # Install from GitHub
       remotes::install_github("pcstrategyandopsco/brightspaceR")

       # Or clone and use the development version
       git clone https://github.com/pcstrategyandopsco/brightspaceR.git

2. OAuth2 credentials configured – the MCP server authenticates using your existing brightspaceR credentials. Follow `vignette("setup")` to register an OAuth2 app and create your `config.yml` or set environment variables.

3. A valid cached token – run `bs_auth()` once in an interactive R session before starting the MCP server. The server reuses the cached token at startup:

       library(brightspaceR)
       bs_auth()
       bs_has_token()
       #> [1] TRUE

4. R packages – the server loads `jsonlite` and `stringr` directly, plus `dplyr`, `tidyr`, `ggplot2`, `lubridate`, and `scales` into the persistent workspace. Install any that are missing:

       install.packages(c("jsonlite", "stringr", "dplyr", "tidyr",
                           "ggplot2", "lubridate", "scales"))

5. pkgload (development mode only) – if running from a local clone rather than an installed package, the server uses `pkgload::load_all()`:

       install.packages("pkgload")

## Locating the server script

The MCP server script lives at `inst/mcp/server.R` inside the package. The exact path depends on how you installed brightspaceR.

From a local clone:

    /path/to/brightspaceR/inst/mcp/server.R

From an installed package:

    system.file("mcp", "server.R", package = "brightspaceR")
    #> "/Library/Frameworks/R.framework/.../brightspaceR/mcp/server.R"

Use the full absolute path in the configuration below.

## Claude Desktop setup

Claude Desktop uses a JSON configuration file to register MCP servers.

### Step 1: Find your config file

Platform | Config file location
--- | ---
macOS | `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows | `%APPDATA%\Claude\claude_desktop_config.json`
Linux | `~/.config/Claude/claude_desktop_config.json`

Create the file if it doesn’t exist.

### Step 2: Add the brightspaceR server

Open the config file and add the `brightspaceR` entry under `mcpServers`. Replace the paths with your actual locations:

    {
      "mcpServers": {
        "brightspaceR": {
          "command": "Rscript",
          "args": ["/Users/you/brightspaceR/inst/mcp/server.R"],
          "cwd": "/Users/you/project-with-config-yml"
        }
      }
    }

Field | Value
--- | ---
`command` | `Rscript` (must be on your PATH)
`args` | Absolute path to `server.R`
`cwd` | Working directory – should contain your `config.yml` with Brightspace credentials. If you use environment variables instead, this can be any directory.

Windows example:

    {
      "mcpServers": {
        "brightspaceR": {
          "command": "Rscript.exe",
          "args": ["C:\\Users\\you\\brightspaceR\\inst\\mcp\\server.R"],
          "cwd": "C:\\Users\\you\\project"
        }
      }
    }

> Tip: If `Rscript` is not on your PATH, use the full path to the executable (e.g., `/usr/local/bin/Rscript` on macOS or `C:\Program Files\R\R-4.4.0\bin\Rscript.exe` on Windows).

### Step 3: Restart Claude Desktop

Quit and reopen Claude Desktop. The brightspaceR server starts automatically. You should see a hammer icon in the chat input area indicating MCP tools are available.

### Step 4: Verify the connection

Type into Claude Desktop:

> Are you connected to Brightspace?

Claude should call the `auth_status` tool and confirm authentication. If it reports `authenticated: false`, run `bs_auth()` in an interactive R session and restart Claude Desktop.

## Claude Code (CLI) setup

Claude Code reads MCP server configuration from `~/.claude.json` (global) or from project-level `.mcp.json` files.

### Option A: Global configuration (~/.claude.json)

Add the server to your `~/.claude.json`:

    {
      "mcpServers": {
        "brightspaceR": {
          "command": "Rscript",
          "args": ["/Users/you/brightspaceR/inst/mcp/server.R"],
          "cwd": "/Users/you/project-with-config-yml"
        }
      }
    }

This makes the brightspaceR tools available in every Claude Code session.

### Option B: Project-level configuration (.mcp.json)

Create a `.mcp.json` file in your project root:

    {
      "mcpServers": {
        "brightspaceR": {
          "command": "Rscript",
          "args": ["/Users/you/brightspaceR/inst/mcp/server.R"],
          "cwd": "."
        }
      }
    }

This limits the MCP server to sessions started in that project directory. Set `cwd` to `"."` if your project root contains the `config.yml`.

### Verify in Claude Code

Start a Claude Code session and type:

    /mcp

You should see `brightspaceR` listed with its 7 tools. Then ask:

> Are you connected to Brightspace?

## Environment variables

The server supports several environment variables for advanced configuration:

Variable | Purpose | Default
--- | --- | ---
`BRIGHTSPACER_PKG_DIR` | Path to brightspaceR package root (overrides auto-detection) | Auto-detected from `server.R` location
`BRIGHTSPACER_OUTPUT_DIR` | Directory for Chart.js HTML and PNG output files | `<pkg_root>/brightspaceR_output` or `<cwd>/brightspaceR_output`
`R_CONFIG_ACTIVE` | Config profile to use from `config.yml` (e.g., `"production"`) | `"default"`

Set these in your MCP server configuration if needed:

    {
      "mcpServers": {
        "brightspaceR": {
          "command": "Rscript",
          "args": ["/Users/you/brightspaceR/inst/mcp/server.R"],
          "cwd": "/Users/you/project",
          "env": {
            "BRIGHTSPACER_OUTPUT_DIR": "/Users/you/Desktop/brightspace_charts",
            "R_CONFIG_ACTIVE": "production"
          }
        }
      }
    }

## Available tools

Once connected, the assistant has access to 7 tools:

Tool | Purpose
--- | ---
`auth_status` | Check authentication status and token validity
`list_datasets` | List all available BDS datasets
`search_datasets` | Search datasets by keyword
`describe_dataset` | Get column names, types, and distribution statistics for a dataset
`list_schemas` | List datasets with known column type schemas
`get_data_summary` | Quick filtered/grouped statistics without writing R code
`execute_r` | Execute arbitrary R code in a persistent workspace with brightspaceR, dplyr, ggplot2, and more pre-loaded

The `execute_r` tool is the most powerful – it lets the assistant write and run any R analysis, from simple filtering to complex multi-dataset joins and interactive Chart.js visualisations.

## Example conversation

After setup, you can ask questions like:

> You: How many students are enrolled in each course?

> Claude calls `list_datasets` to discover “User Enrollments”, then uses `execute_r` to download and count enrollments per course.

> You: Show me the grade distribution for STAT101.

> Claude uses `execute_r` to filter Grade Results, calculate summary statistics, and generate an interactive Chart.js histogram saved to your output directory.

> You: Which students haven’t logged in for 2 weeks?

> Claude uses `execute_r` with `bs_identify_at_risk()` to flag inactive students and returns a summary table.

See `vignette("mcp-server-design")` for architecture details, and `vignette("mcp-test-script")` for a full set of test prompts to verify your setup.

## Troubleshooting

### Server not starting

Run the server manually to see startup messages:

    Rscript /path/to/brightspaceR/inst/mcp/server.R

You should see diagnostic output on stderr. Common issues:

- “cannot open file ‘…’: No such file or directory” – check the path in your config
- “there is no package called ‘brightspaceR’” – install the package or set `BRIGHTSPACER_PKG_DIR`
- “there is no package called ‘pkgload’” – install pkgload: `install.packages("pkgload")`

### Authentication failures

The server reuses cached OAuth2 tokens. If authentication fails:

1. Run `bs_auth()` in an interactive R session
2. Verify with `bs_has_token()` – should return `TRUE`
3. Restart Claude Desktop / Claude Code

### No tools appearing in Claude Desktop

- Check that the config file is valid JSON (no trailing commas)
- Verify `Rscript` is on your PATH: `which Rscript` (macOS/Linux) or `where Rscript.exe` (Windows)
- Make sure you restarted Claude Desktop after editing the config

### Visualisations not appearing

Check the output directory:

    # In Claude, ask:
    # "What is the current output directory?"
    # Claude will check via execute_r:
    output_dir

Make sure the directory exists and is writable. You can override it with the `BRIGHTSPACER_OUTPUT_DIR` environment variable.