Getting Started with MCPR

Getting Started with MCPR: Your First Session

MCPR (Model Context Protocol for R) gives your AI assistant a persistent R workspace. By default, that workspace is the private R process running MCPR::mcpr_server(). When you want the agent to work inside an existing interactive R console, you can make that console attachable with mcpr_session_start() and switch the active session with manage_r_sessions().

Installation and Setup

# Install MCPR
if (!require("remotes")) install.packages("remotes")
remotes::install_github("phisanti/MCPR")

# Configure your AI agent (Claude, Gemini, or Copilot)
library(MCPR)
install_mcpr(agent = "claude")

Your First MCPR Experience

Let’s walk through a basic session to see how MCPR works in practice.

Step 1: Use the Private Session

# Your MCP client launches this through its configuration
MCPR::mcpr_server()

The MCP server process is also the agent’s private R session. Variables created by ordinary tools persist there until the server process exits.

Step 2: Check the Workspace

Now you can ask your AI assistant:

You: “What variables are in the R workspace?”

Your AI will use MCPR tools to respond:

# Check current variables
ls()
# Shows objects in the private session

Step 3: Create Some Variables

You: “Can you create some random variables?”

Your AI assistant executes:

# Create multiple variables efficiently
random_numbers <- runif(15, 1, 100)
random_matrix <- matrix(rnorm(12), nrow = 3, ncol = 4)
random_names <- sample(c("Alice", "Bob", "Charlie", "Diana", "Eve"), 8, replace = TRUE)
random_df <- data.frame(
  id = 1:6,
  value = rnorm(6, mean = 50, sd = 10),
  category = sample(letters[1:3], 6, replace = TRUE)
)

# Verify creation
ls()

Key insight: All these variables now persist in the private session and remain available for future operations.

Step 4: Optionally Attach a Live R Session

You: “I want you to work inside my existing R console”

In that R console, run:

library(MCPR)
mcpr_session_start()

Then ask your AI:

You: “List attachable sessions and join mine”

Your AI will:

manage_r_sessions("list")
manage_r_sessions("join", session = 1)

Ordinary tool calls still omit session; after joining, MCPR sends them to the active attached session. Use manage_r_sessions("detach") to return to the private session.

Step 5: Session Independence

Key discovery: The private session, human sessions, and MCPR-owned secondary sessions maintain independent workspaces. Attaching changes the active execution target; it does not merge workspaces.

Core MCPR Tools

Session Management

# List all active sessions
manage_r_sessions("list")

# Join a specific session
manage_r_sessions("join", session = 2)

# Return to the private session
manage_r_sessions("detach")

Code Execution

# Execute R code in the active session
execute_r_code("
  summary(random_df)
  plot(random_numbers)
")

Workspace Inspection

# View current objects
view("session")

# View command history
view("terminal")

# View file system
view("workspace")

Plot Creation

# Show a plot to the user
show_plot("
  hist(random_numbers, main = 'Random Numbers Distribution')
")

Conclusion

This little demo aims to show the capabilities of MCPR. It provides a persistent R environment that bridges the gap between traditional scripting and interactive AI agent collaboration:

• Stateful Programming: Your AI agent maintains context in a persistent private workspace
• Parallel Workflows: Private, human, and secondary sessions let you compartmentalize different projects
• Controlled Attachment: Move between sessions with manage_r_sessions while ordinary tools stay simple
• Interactive Analysis: Discuss data, iterate on visualizations, and explore findings conversationally
• Persistent Collaboration: Build complex analyses incrementally with your AI agent as a programming partner

MCPR transforms R from isolated script execution into a collaborative workspace where your AI agent becomes an extension of your analytical thinking—whether you’re exploring datasets, debugging complex models, or building reproducible research workflows.

Troubleshooting

“No attachable sessions found”: If you want to attach to a live R console, start one with mcpr_session_start()

“Connection failed”: Verify MCPR installation with install_mcpr()

“Variables not found”: Check the active session with manage_r_sessions("list"), or detach back to private/local execution with manage_r_sessions("detach")

Next Steps

• AI Agent Integration: Configure your specific AI agent
• Tool Development: Create custom tools for your workflow
• Architecture Overview: Understand how MCPR works internally

You’re now ready to use MCPR for persistent, collaborative R programming with your AI assistant!