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') - Show the private session, active session, and attachable sessions
  • manage_r_sessions('join', session=ID) - Attach to a human session started with mcpr_session_start()
  • manage_r_sessions('start') - Start and attach an MCPR-owned secondary session
  • manage_r_sessions('detach') - Return ordinary tools to the private/local session

Code Execution

  • execute_r_code(code) - Run R code in the active session. Do not pass a session argument.

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. The MCP client starts MCPR::mcpr_server().
  2. Load data in the private session: execute_r_code("data <- read.csv('data.csv')")
  3. Explore: view('session') to see loaded objects
  4. Visualize: show_plot("plot(data$x, data$y)")
  5. Optionally attach to a live R console with manage_r_sessions('join', session=ID)
  6. Detach back to private/local execution with manage_r_sessions('detach')

Multi-Session Development

  • Private session: agent-owned package work
  • Human session: live interactive console made attachable with mcpr_session_start()
  • Secondary session: MCPR-owned process created by manage_r_sessions('start')

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 can cause the AI agent’s private MCPR server process to use a different instance or version of MCPR than an interactive R console you later attach.

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.