MCPR: A Practical Framework for Stateful Human-AI Collaboration in R

The MCPR (Model Context Protocol Tools for R) package addresses a
fundamental limitation in the current paradigm of AI-assisted R
programming. Existing AI agents operate in a stateless execution model,
invoking Rscript for each command, which is antithetical to the
iterative, state-dependent nature of serious data analysis. An
analytical workflow is a cumulative process of exploration, modelling,
and validation that can span hours or days. Moreover, intermediate steps
can involve heavy computation, and small changes in downstream code such
as plot aesthetics require running the entire script again. MCPR aims to
tackle this issue by enabling AI agents to establish persistent,
interactive sessions within a live R environment, thereby preserving
workspace state and enabling complex, multi-step analytical workflows.

Quick Start

Get up and running with MCPR in under 2 minutes:

# 1. Install MCPR
remotes::install_github("phisanti/MCPR")

# 2. Start an R session and make it discoverable
library(MCPR)
mcpr_session_start()

# 3. In your AI agent (Claude, etc.), connect to the session
# The agent will use: manage_r_sessions("list") then manage_r_sessions("join", session_id)

# 4. Now your AI agent can run R code in your live session!
# Example: execute_r_code("summary(mtcars)")

That’s it! Your AI agent can now execute R code, create plots, and
inspect your workspace while preserving all session state.

Core capabilities

MCPR’s design is guided by principles of modularity, robustness, and
practicality.

Communication Protocol: MCPR uses JSON-RPC 2.0 over nanonext
sockets, providing a lightweight, asynchronous, and reliable messaging
layer. This choice ensures cross-platform compatibility and
non-blocking communication suitable for an interactive environment.
Tool-Based Design: Functionality is exposed to the AI agent as a
discrete set of tools (create_plot, execute_r_code, etc.). This
modular approach simplifies the agent’s interaction logic and provides
clear, well-defined endpoints for R operations.
Session Management: A central mcpr_session_start() function acts
as a listener, making an R session discoverable on the local machine.
The manage_r_sessions tool provides the service discovery mechanism
for agents to find and connect to these listeners.
Graphics Subsystem: Plot generation leverages httpgd when
available for high-performance, off-screen rendering. A fallback to
standard R graphics devices (grDevices) ensures broad compatibility.
The system includes intelligent token management to prevent oversized
image payloads.

Installation

The first requirement is to have R installed and then install the MCPR
package from GitHub:

if (!require("remotes")) install.packages("remotes")

remotes::install_github("phisanti/MCPR")

Next, you should install the MCP server to give the agent access to the
tools included in the package. System integration is designed to be
straightforward, with both automated and manual pathways.

Automated Setup

A convenience function, install_mcpr(), is provided to handle package
installation and agent-specific MCP configuration. Supported agents
include Claude, Gemini, Copilot, and Codex.

library(MCPR)
install_mcpr(agent = "claude") # Supported agents: 'claude', 'gemini', 'copilot', 'codex'

Manual MCP Configuration

For Claude Desktop, configure claude_desktop_config.json. You can
likely find it in one of these locations depending on your OS:

macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json Linux:
~/.config/claude/claude_desktop_config.json

Then, add the following MCP server configuration:

{
  "mcpServers": {
    "mcpr": {
      "command": "R",
      "args": ["--quiet", "--slave", "-e", "MCPR::mcpr_server()"]
    }
  }
}

Supported agents

Currently, MCPR supports configuration for the following AI agents with
the given configuration paths (note that these are approximate and might
vary based on OS and installation):

Claude: Claude Desktop config at
~/Library/Application Support/Claude/claude_desktop_config.json
(macOS), %APPDATA%/Claude/claude_desktop_config.json (Windows), or
~/.config/Claude/claude_desktop_config.json (Linux).
Gemini: Global settings at ~/.gemini/settings.json (use
./.gemini/settings.json for a project-local setup).
Copilot: Workspace configuration at .vscode/mcp.json (user-level
fallback at ~/.config/Code/User/mcp.json or
%APPDATA%/Code/User/mcp.json).
Codex: Global TOML configuration at ~/.codex/config.toml.

Usage Pattern

The intended workflow is simple and user-centric.

The user starts an R session and invokes mcpr_session_start() to
enable connections.
The user instructs their AI agent to connect.
The agent uses manage_r_sessions('list') to find the session ID
and manage_r_sessions('join', session=ID) to connect.
The user can now interact with the agent, making requests regarding
their R session. The agent can now use execute_r_code,
create_plot, and view to collaboratively assist the user with
their analysis, maintaining full context throughout the interaction.

Agent tools

The philosophy in the development of the MCPR package is to provide the
agent with few, well-defined tools that can be composed to perform
complex tasks. The goal was to give the agent the ability to manage
multiple R sessions (manage_r_sessions), to run R code in the session
(execute_r_code), see the graphical data (create_plot), and inspect
the session (view). We believe these are flexible enough to accomplish
any task in R. See the details below.

`execute_r_code(code)`

Purpose: Execute arbitrary R code within session context
Input: Character string containing R expressions
Output: Structured response with results, output, warnings, and
errors

execute_r_code("
  library(dplyr)
  data <- mtcars %>% 
    filter(mpg > 20) %>%
    select(mpg, cyl, wt)
  nrow(data)
")

`create_plot(expr, width, height, format)`

Purpose: Generate visualizations with AI-optimized output
Input: R plotting expression, dimensions, format specification
Output: Base64-encoded image with metadata and token usage
information

create_plot("
  library(ggplot2)
  ggplot(mtcars, aes(wt, mpg)) + 
    geom_point() + 
    geom_smooth(method = 'lm')
", width = 600, height = 450)

`manage_r_sessions(action, session)`

Purpose: Session discovery and management
Actions:

"list": Enumerate active sessions with metadata
"join": Connect to specific session by ID
"start": Launch new R session process

manage_r_sessions("list")        # Show available sessions
manage_r_sessions("join", 2)     # Connect to session 2
manage_r_sessions("start")       # Create new session

`view(what, max_lines)`

Purpose: Environment introspection and debugging
what:

'session': Object summaries with statistical metadata
'terminal': Command history for workflow reproducibility
'workspace': File system context
'installed_packages': Available libraries

Common errors

Connection Failed: Ensure mcpr_session_start() is running in R.
Set the MCPTOOLS_LOG_FILE environment variable to a valid path and
inspect logs for detailed error messages.
Tools Not Found: Confirm the path in user_mcp.json is correct
and that the agent has been restarted. Manually install the MCP server
to verify the setup.
Plotting Errors: Ensure the plotting expression is valid and that
all necessary libraries are loaded, and install httpgd.

If these issues persist, please open an issue on the GitHub repository
with relevant logs and context.

Acknowledgments

We thank Simon P. Couch
(mcptools) for the inspiration
to use nanonext and Aleksander
Dietrichson
(mcpr) for the idea of using
roxygen2 for parsing tools.

This project is licensed under the Creative Commons Attribution 4.0
International License.