Configure putior MCP Server

Set up putior MCP server → AI assistants (Claude Code, Claude Desktop) can directly call workflow annotation + diagram gen tools.

Use When

• Enable AI assistants to interactively annotate + visualize workflows
• Set up new dev env w/ putior MCP integration
• Post-install putior → want AI-assisted workflow docs
• Configure agent-to-agent comm via ACP for automated pipelines

In

• Required: putior installed (see

  install-putior

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

Do

Step 1: Install MCP Dependencies

Install req'd pkgs 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)

→ Both pkgs install + load w/o errs.

If err:

mcptools

requires

remotes

pkg. Install first:

install.packages("remotes")

. GitHub rate-limits → configure

GITHUB_PAT

in

~/.Renviron

(add line

GITHUB_PAT=your_token_here

+ restart R). Do NOT paste tokens into shell cmds or commit to version control.

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

Add putior MCP server to Claude Code's config.

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

For WSL w/ Windows R:

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

Verify config:

claude mcp list
claude mcp get putior

→

putior

appears in MCP server list w/ status "configured".

If err: Claude Code not in PATH → add:

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

. Rscript path wrong → locate R w/

which Rscript

or

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

.

Step 3: Configure Claude Desktop (Windows)

Add putior to Claude Desktop's MCP config 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 w/ 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 post-edit.

→ Claude Desktop shows putior in MCP server list. Tools become avail in conversation.

If err: Valid. JSON syntax w/ JSON linter. Check 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 all MCP tools accessible + 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))

16 tools organized by category:

Core Workflow (5):

• put

  — Scan files for PUT annotations (supports

  exclude

  param for regex-based file filtering)

• put_diagram

  — Generate Mermaid diagrams

• put_auto

  — Auto-detect workflow from code (supports

  exclude

  param)

• put_generate

  — Gen annotation suggestions (supports

  exclude

  param)

• put_merge

  — Merge manual + auto annotations (supports

  exclude

  param)

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 docs

• putior_help

  — Quick reference help

Utilities (3):

• is_valid_put_annotation

  — Valid. 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 can't be used through MCP.

palette

param on

put_diagram

accepts

putior_theme

R object created by

put_theme()

. MCP comms via JSON → R objects like

putior_theme

can't be serialized across MCP boundary. Calling

put_diagram

through MCP → use string-based

theme

param (e.g.,

theme = "viridis"

) instead. Custom palettes → call

put_theme()

+

put_diagram(palette = ...)

directly in 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

→ All 16 tools listed. Core tools return expected results when called w/ valid in.

If err: Tools missing → check putior ver current:

packageVersion("putior")

. Older vers may have fewer tools. Update w/

remotes::install_github("pjt222/putior")

.

Step 5: Configure ACP Server (Optional)

Set up ACP (Agent Comm Protocol) server for agent-to-agent comm.

# 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/"}]}]}'

→ ACP server starts on config'd port.

/agents

returns putior agent manifest.

/runs

accepts natural language reqs + returns workflow results.

If err: Port 8080 in use → specify diff port.

plumber2

not installed → server fn will print helpful err msg suggesting install.

Check

• putior::putior_mcp_tools()

  exposes core tools (

  put

  ,

  put_diagram

  ,

  put_auto

  ,

  put_generate

  ,

  put_merge

  ) + returns ~16 tools for current ver
• Claude Code:

  claude mcp list

  shows

  putior

  configured
• Claude Code:

  putior_help

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

  put

  ,

  put_diagram

  ,

  put_auto

  ) execute w/o errs
• (Optional) ACP server responds to

  curl http://localhost:8080/agents

Traps

• mcptools not installed: MCP server requires

  mcptools

  (from GitHub) +

  ellmer

  (from CRAN). Both must be installed. putior checks + provides helpful msgs if 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

  .
• Forget to restart: Claude Desktop must be restarted post-config edit. Claude Code picks up changes on next session start.
• renv isolation: putior installed in renv library but Claude Code/Desktop launches R w/o renv → pkgs not found. Ensure

  mcptools

  +

  ellmer

  installed in global library or configure renv activation in MCP server cmd.
• Port conflicts for ACP: Default ACP port (8080) commonly used. Check w/

  lsof -i :8080

  or

  netstat -tlnp | grep 8080

  before starting.
• Include only specific tools: Expose subset of tools → use

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

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

  palette

  param on

  put_diagram

  requires

  putior_theme

  R object (created by

  put_theme()

  ), can't be serialized through MCP's JSON interface. Use built-in

  theme

  param string for MCP calls. Custom palettes → use R directly.

→

• install-putior

  — prerequisite: putior + optional deps must be installed

• configure-mcp-server

  — general MCP server config for Claude Code/Desktop

• troubleshoot-mcp-connection

  — diagnose connection issues if tools don't appear

• build-custom-mcp-server

  — build custom MCP servers wrapping putior tools

• analyze-codebase-workflow

  — use MCP tools interactively for codebase analysis