MCP Server Setup

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, stringr, and yaml directly, plus dplyr, tidyr, ggplot2, lubridate, and scales into the persistent workspace. Install any that are missing:

   install.packages(c("jsonlite", "stringr", "yaml", "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.

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

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

Claude Code (CLI) setup

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

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

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

/mcp

Environment variables

The server supports several environment variables for advanced configuration:

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:

The execute_r tool is the most powerful – it lets the assistant write and run R analysis, from simple filtering to complex multi-dataset joins and interactive Chart.js visualisations. Code is inspected before execution to block dangerous constructs (shell commands, file I/O, direct API access), and datasets are filtered through a PII field policy that strips sensitive columns like names and emails before they reach the workspace.

Use write_chart(html, 'name.html') to save Chart.js HTML output safely to the output directory.

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.

Security

The MCP server includes four security layers enabled by default:

AST code inspection – R code submitted via execute_r is parsed and checked before execution. Dangerous constructs are blocked: direct package access (brightspaceR::, httr::, curl::, etc.), metaprogramming (eval, do.call, get), shell commands (system, system2), file I/O (readLines, writeLines, etc.), and network functions (download.file, url). Use write_chart() for Chart.js HTML output.

PII field policy – A YAML policy file controls which columns are visible per dataset. The default policy (inst/mcp/field_policy.yml) hides PII columns like names, emails, and free-text comments from datasets like Users and Grade Results. Override with a custom policy via BRIGHTSPACER_FIELD_POLICY.

ID pseudonymisation – All person-referencing ID columns (UserId, SubmitterId, LastModifiedBy, etc.) are HMAC-hashed with a session-scoped key. The AI model sees deterministic pseudonyms like usr_a3f2b1c8 instead of raw integers. Combined with the field policy, this means no names, no emails, and no reversible IDs reach the model.

Audit logging – Every tool call is recorded in mcp_audit.jsonl in the output directory. Entries include timestamp, tool name, arguments, response size, and whether code was blocked.

See vignette("mcp-server-design") for implementation details and vignette("privacy-compliance") for a full assessment against ENISA, NIST, ISO 25237, GDPR, and FERPA standards — including how to apply the same protections in regular R scripts.

Troubleshooting

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

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