Skip to contents

MCP Setup

Source: vignettes/mcp-setup.Rmd
mcp-setup.Rmd

AI Agent Integration Guide

This guide covers how to integrate MCPR with different AI coding assistants.

Supported Agents

MCPR currently supports: - Claude Desktop - Gemini (via MCP) - GitHub Copilot (via MCP)

Claude Desktop Setup

Automatic Configuration 

library(MCPR)
install_mcpr(agent = "claude")

Manual Configuration

Edit your Claude Desktop config file:

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

Add the MCP server configuration:

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

Using MCPR Tools

Once configured, your AI agent will have access to these tools:

Session Management

  • manage_r_sessions('list') - List active R sessions
  • manage_r_sessions('join', session=ID) - Connect to a session
  • manage_r_sessions('start') - Start a new session

Code Execution

  • execute_r_code(code) - Run R code in the connected session

Visualization

  • show_plot(expr, target, ...) - Create and display plots (target=‘user’ or ‘agent’)

Inspection

  • view('session') - View workspace objects
  • view('terminal') - View command history
  • view('workspace') - View file system context

Workflow Examples

Data Analysis Workflow

  1. Start R session: mcpr_session_start()
  2. Agent joins session: manage_r_sessions('join', session=1)
  3. Load data: execute_r_code("data <- read.csv('data.csv')")
  4. Explore: view('session') to see loaded objects
  5. Visualize: show_plot("plot(data$x, data$y)")
  6. Iterate and refine analysis

Multi-Session Development

  • Session 1: Data preprocessing
  • Session 2: Model development
  • Session 3: Visualization and reporting

Troubleshooting

Agent can’t see tools: Restart the agent after configuration.

Permission errors: Check file paths and R library permissions.

Connection timeouts: Increase timeout in MCP configuration.

Advanced Configuration

Custom Tool Paths 

{
  "mcpServers": {
    "mcpr": {
      "command": "R",
      "args": ["--quiet", "--slave", "-e", "MCPR::mcpr_server()"],
      "env": {
        "MCPTOOLS_TOOLS_DIR": "/path/to/custom/tools",
        "MCPTOOLS_LOG_FILE": "/path/to/logs/mcpr.log"
      }
    }
  }
}

Environment Variables

  • MCPTOOLS_LOG_FILE: Path for debug logs
  • MCPTOOLS_TOOLS_DIR: Custom tools directory
  • R_LIBS_USER: R library path

Common Issues

Working with MCPR in renv Projects

When using MCPR with AI agents (like Claude Desktop or Codex) in renv-enabled projects, you may encounter connection issues where the agent cannot find or load the MCPR package.

Problem: The MCP server fails to start or behaves unexpectedly because renv isolates the project’s R library. This causes the AI agent to run a different instance or version of MCPR (installed in the global library) than the one you are running in your interactive R session (often in the local library), leading to communication mismatches.

Solution: Configure renv to use your global MCPR installation by creating a scaffold file before initializing renv:

  1. Before running renv::init(), create a file called scaffold.R in your project root:
# scaffold.R
library(MCPR)
  1. Initialize renv normally:
renv::init()

This approach ensures that renv detects MCPR as a dependency and links to your global installation rather than trying to install a separate copy. This is similar to the recommended approach for VSCode-R with renv.

For existing renv projects:

If you already have an renv project without MCPR, you can add it:

# Install MCPR into the renv library
renv::install("path/to/MCPR", repos = NULL, type = "source")

# Or use the global installation
renv::use_package("MCPR", type = "Imports", dev = TRUE)
renv::snapshot()

GitHub Copilot / Codex Configuration Issues

Some newer versions of AI coding assistants require explicit specification of the MCP server connection type.

Problem: MCP server fails to connect with error messages like “handshaking with MCP server failed” or “connection closed: initialize response”.

Solution: Ensure your configuration file explicitly declares "type": "stdio".

Correct configuration for ~/.vscode/mcp.json or equivalent:

{
    "servers": {
        "MCPR": {
            "type": "stdio",
            "command": "R",
            "args": [
                "--quiet",
                "--slave",
                "-e",
                "MCPR::mcpr_server()"
            ]
        }
    },
    "inputs": []
}

Key points: - The "type": "stdio" field is required for newer MCP client implementations - Without this field, the client may fail to establish the communication channel - The "inputs": [] field may also be required by some clients

Protocol Version Mismatches

Different AI coding agents support different MCP protocol versions. MCPR implements protocol version negotiation to handle this automatically.

Supported versions: - 2024-11-05 (baseline) - 2025-03-26 - 2025-06-18 - 2025-11-25 (latest)

If you encounter version-related errors, check your agent’s logs for protocol version information. MCPR should automatically negotiate the highest mutually supported version.