Configure putior MCP Server

Set up the putior MCP server so AI assistants (Claude Code, Claude Desktop) can directly call workflow annotation and diagram generation tools.

When to Use

• Enabling AI assistants to interactively annotate and visualize workflows
• Setting up a new development environment with putior MCP integration
• After installing putior and wanting AI-assisted workflow documentation
• Configuring agent-to-agent communication via ACP for automated pipelines

Inputs

• Required: putior installed (see

  install-putior

  )
• Required: Target client: Claude Code, Claude Desktop, or both
• Optional: Whether to also configure ACP server (default: no)
• Optional: Custom host/port for ACP server (default: localhost:8080)

Procedure

Step 1: Install MCP Dependencies

Install the required packages for MCP server functionality.

# Required: MCP framework
remotes::install_github("posit-dev/mcptools")

# Required: Tool definition framework
install.packages("ellmer")

# Verify both load
library(mcptools)
library(ellmer)

Expected: Both packages install and load without errors.

On failure:

mcptools

requires

remotes

package. Install it first:

install.packages("remotes")

. If GitHub rate-limits, configure a

GITHUB_PAT

in

~/.Renviron

(add the line

GITHUB_PAT=your_token_here

and restart R). Do not paste tokens into shell commands or commit them to version control.

Step 2: Configure Claude Code (WSL/Linux/macOS)

Add the putior MCP server to Claude Code's configuration.

# One-line setup
claude mcp add putior -- Rscript -e "putior::putior_mcp_server()"

For WSL with Windows R:

claude mcp add putior -- "/mnt/c/Program Files/R/R-4.5.2/bin/Rscript.exe" -e "putior::putior_mcp_server()"

Verify the configuration:

claude mcp list
claude mcp get putior

Expected:

putior

appears in the MCP server list with status "configured".

On failure: If Claude Code is not in PATH, add it:

export PATH="$HOME/.claude/local/node_modules/.bin:$PATH"

. If the Rscript path is wrong, locate R with

which Rscript

or

ls "/mnt/c/Program Files/R/"

.

Step 3: Configure Claude Desktop (Windows)

Add putior to Claude Desktop's MCP configuration file.

Edit

%APPDATA%\Claude\claude_desktop_config.json

:

{
  "mcpServers": {
    "putior": {
      "command": "C:\\PROGRA~1\\R\\R-45~1.0\\bin\\x64\\Rscript.exe",
      "args": ["-e", "putior::putior_mcp_server()"]
    }
  }
}

Or with the full path:

{
  "mcpServers": {
    "putior": {
      "command": "C:\\Program Files\\R\\R-4.5.2\\bin\\x64\\Rscript.exe",
      "args": ["-e", "putior::putior_mcp_server()"]
    }
  }
}

Restart Claude Desktop after editing the configuration.

Expected: Claude Desktop shows putior in its MCP server list. Tools become available in conversation.

On failure: Validate JSON syntax with a JSON linter. Check that the R path exists. Use 8.3 short names (

PROGRA~1

,

R-45~1.0

) if spaces in paths cause issues.

Step 4: Verify All 16 Tools

Test that all MCP tools are accessible and functional.

# Get tool definitions
tools <- putior::putior_mcp_tools()
cat(sprintf("Total tools: %d\n", length(tools)))

# List tool names
vapply(tools, function(t) t$name, character(1))

The 16 tools organized by category:

Core Workflow (5):

• put

  — Scan files for PUT annotations (supports

  exclude

  parameter for regex-based file filtering)

• put_diagram

  — Generate Mermaid diagrams

• put_auto

  — Auto-detect workflow from code (supports

  exclude

  parameter)

• put_generate

  — Generate annotation suggestions (supports

  exclude

  parameter)

• put_merge

  — Merge manual + auto annotations (supports

  exclude

  parameter)

Reference/Discovery (7):

• get_comment_prefix

  — Get comment prefix for extension

• get_supported_extensions

  — List supported extensions

• list_supported_languages

  — List supported languages

• get_detection_patterns

  — Get auto-detection patterns

• get_diagram_themes

  — List available themes

• putior_guide

  — AI assistant documentation

• putior_help

  — Quick reference help

Utilities (3):

• is_valid_put_annotation

  — Validate annotation syntax

• split_file_list

  — Parse file lists

• ext_to_language

  — Extension to language name

Configuration (1):

• set_putior_log_level

  — Configure logging verbosity

Important: Custom palettes cannot be used through MCP. The

palette

parameter on

put_diagram

accepts a

putior_theme

R object created by

put_theme()

. Because MCP communicates via JSON, R objects like

putior_theme

cannot be serialized across the MCP boundary. When calling

put_diagram

through MCP, use the string-based

theme

parameter (e.g.,

theme = "viridis"

) instead. For custom palettes, call

put_theme()

and

put_diagram(palette = ...)

directly in an R session.

Test core tools from Claude Code:

Use the putior_help tool to see available commands
Use the put tool to scan ./R/ for annotations
Use the put_diagram tool to generate a diagram

Expected: All 16 tools listed. Core tools return expected results when called with valid inputs.

On failure: If tools are missing, check that putior version is current:

packageVersion("putior")

. Older versions may have fewer tools. Update with

remotes::install_github("pjt222/putior")

.

Step 5: Configure ACP Server (Optional)

Set up the ACP (Agent Communication Protocol) server for agent-to-agent communication.

# Install ACP dependency
install.packages("plumber2")

# Start ACP server (blocks — run in a separate R session or background)
putior::putior_acp_server()

# Custom host/port
putior::putior_acp_server(host = "0.0.0.0", port = 9000)

Test ACP endpoints:

# Discover agent
curl http://localhost:8080/agents

# Execute a scan
curl -X POST http://localhost:8080/runs \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "parts": [{"content": "scan ./R/"}]}]}'

# Generate diagram
curl -X POST http://localhost:8080/runs \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "parts": [{"content": "generate diagram for ./R/"}]}]}'

Expected: ACP server starts on the configured port.

/agents

returns the putior agent manifest.

/runs

accepts natural language requests and returns workflow results.

On failure: If port 8080 is in use, specify a different port. If

plumber2

is not installed, the server function will print a helpful error message suggesting installation.

Validation

• putior::putior_mcp_tools()

  exposes the core tools (

  put

  ,

  put_diagram

  ,

  put_auto

  ,

  put_generate

  ,

  put_merge

  ) and returns ~16 tools for the current version
• Claude Code:

  claude mcp list

  shows

  putior

  configured
• Claude Code:

  putior_help

  tool returns help text when invoked
• Claude Desktop: putior appears in the MCP server list after restart
• Core tools (

  put

  ,

  put_diagram

  ,

  put_auto

  ) execute without errors
• (Optional) ACP server responds to

  curl http://localhost:8080/agents

Common Pitfalls

• mcptools not installed: The MCP server requires

  mcptools

  (from GitHub) and

  ellmer

  (from CRAN). Both must be installed. putior checks and provides helpful messages if they're missing.
• Wrong R path in Claude Desktop: Windows paths need escaping in JSON (

  \\

  ). Use 8.3 short names to avoid spaces:

  C:\\PROGRA~1\\R\\R-45~1.0\\bin\\x64\\Rscript.exe

  .
• Forgetting to restart: Claude Desktop must be restarted after editing the config file. Claude Code picks up changes on next session start.
• renv isolation: If putior is installed in an renv library but Claude Code/Desktop launches R without renv, the packages won't be found. Ensure

  mcptools

  and

  ellmer

  are installed in the global library or configure renv activation in the MCP server command.
• Port conflicts for ACP: The default ACP port (8080) is commonly used. Check with

  lsof -i :8080

  or

  netstat -tlnp | grep 8080

  before starting.
• Including only specific tools: To expose a subset of tools, use

  putior_mcp_tools(include = c("put", "put_diagram"))

  when building custom MCP server wrappers.
• Custom palettes via MCP: The

  palette

  parameter on

  put_diagram

  requires a

  putior_theme

  R object (created by

  put_theme()

  ), which cannot be serialized through MCP's JSON interface. Use the built-in

  theme

  parameter string for MCP calls. For custom palettes, use R directly.

Related Skills

• install-putior

  — prerequisite: putior and optional deps must be installed

• configure-mcp-server

  — general MCP server configuration for Claude Code/Desktop

• troubleshoot-mcp-connection

  — diagnose connection issues if tools don't appear

• build-custom-mcp-server

  — build custom MCP servers that wrap putior tools

• analyze-codebase-workflow

  — use MCP tools interactively for codebase analysis