Getting Started with PumasAide

This guide walks through setting up PumasAide for AI-assisted pharmacometric analysis. Setup differs depending on whether you're working in JuliaHub or on a desktop environment.

JuliaHub Setup

JuliaHub includes Claude Code pre-installed. If you prefer an alternative, we recommend Kilo Code—see Kilo Code setup below for configuration.

1. Start PumasAide Server

Open a Julia REPL in your JuliaHub environment and start the PumasAide server:

import PumasAide

# Start the server (runs on port 8081)
PumasAide.Server.serve()

The server will start and display:

PumasAide MCP Server running on http://localhost:8081

Keep this Julia session running while you work.

2. Configure Claude Code (first time only)

Connect Claude Code to PumasAide:

claude mcp add --scope user --transport http pumasaide http://localhost:8081/mcp

3. Begin Your Analysis

Run claude from your project folder—this limits access to only the content needed for your analysis. Describe your goals in natural language:

Load the concentration-time data from pkdata.csv and perform
a non-compartmental analysis calculating AUC, Cmax, and half-life.

Claude Code will detect the PumasAide tools and execute the appropriate workflow.

4. View Results

PumasAide organizes outputs into three directories:

project/
├── programs/           # Generated Julia scripts (executable, version-controlled)
├── notes/              # Analysis notes (findings, decisions across sessions)
└── reports/            # Formal Quarto reports (final deliverables)

Visit http://localhost:8081/preview for interactive plots and tables.

Desktop users can connect any MCP-compatible AI coding assistant to PumasAide. We recommend GitHub Copilot with VS Code, but any tool supporting streamable HTTP transport from the MCP specification will work.

1. Start Julia and Import PumasAide

Open a Julia REPL in your project directory and import PumasAide (included with Pumas):

import PumasAide
PumasAide.Server.serve()

Keep this session running while you work.

2. Configure Your AI Assistant

Choose your AI coding assistant and follow the corresponding setup:

Claude Code

Install Claude Code, then run:

claude mcp add --scope user --transport http pumasaide http://localhost:8081/mcp

See Claude Code MCP documentation for details.

GitHub Copilot

Requires VS Code 1.99 or later with the GitHub Copilot extension.

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Run MCP: Add Server
Select HTTP (Server-Sent Events)
Enter URL: http://localhost:8081/mcp
Enter Server ID: PumasAide
Choose Global (all projects) or Workspace (current project only)

See VS Code MCP documentation for details.

Kilo Code

Install the Kilo Code VS Code extension.

Add to global MCP settings (via extension settings) or project .kilocode/mcp.json:

{
  "mcpServers": {
    "PumasAide": {
      "type": "streamable-http",
      "url": "http://localhost:8081/mcp"
    }
  }
}

See Kilo Code MCP documentation for details.

3. Verify Connection

Restart your AI assistant after configuring the MCP server. To verify:

Ask: "What PumasAide tools are available?"
The assistant should list tools for data loading, modeling, NCA, plotting, etc.
If no tools appear, check that port 8081 is available and your assistant supports MCP with streamable HTTP transport

Try a simple analysis to confirm everything works. See NCA Analysis Walkthrough or Population PK Walkthrough for complete examples.

Recommended AI Models

Models from Anthropic, OpenAI, or Google work best. Any recent reasoning model that supports MCP tool calling is compatible.

First-Time Users: Interactive Tutorial

If you're new to PumasAide, start with an interactive tutorial:

Start the interactive tutorial for NCA analysis

The tutorial will guide you through:

Loading example concentration-time data
Exploring the data with visualizations
Running NCA calculations
Interpreting results
Generating a summary report

You can also ask for tutorials on other topics: "Start the interactive tutorial for population PK" or "Start the interactive tutorial for simulation."

Learning While Doing

Watch the tool calls as you work through the tutorial. Each call shows you the exact parameters being used, helping you learn Pumas patterns naturally.

Working Across Sessions

The AI maintains project context through the notes/ directory. In a new session, ask about previous work:

"What's the status of the study_123 analysis?"
"Why did we choose the two-compartment model?"
"Document that Subject 015 was excluded due to missed dose"

Tips for Effective Prompts

State goals clearly: What parameters do you need? What decisions depend on results?
Provide context: Single vs multiple dose? IV vs oral? Study design?
Request visualizations: Ask for specific plots you need
Build incrementally: Start simple, add complexity based on results
Iterate freely: Refine analyses based on initial results

Next Steps

Workflows to learn about built-in analysis workflows
Tools Reference for detailed documentation of all available tools
NCA Analysis Walkthrough and Population PK Walkthrough for step-by-step tutorials
Troubleshooting if you encounter issues

Troubleshooting

Server won't start

Port already in use: Another process is using port 8081. Either stop the other process or specify a different port:

PumasAide.Server.serve(port = 8082)

AI assistant doesn't detect tools

Restart required: Restart your AI assistant after adding MCP server configuration.

MCP support: Confirm your AI assistant version supports the Model Context Protocol with streamable HTTP transport.

Generated code errors

Missing packages: Ensure your Julia environment includes Pumas and its dependencies. Generated code uses standard Pumas packages.

Working directory: Run code from the directory where programs/ was created, so relative paths resolve correctly.

The AI gave unexpected results

Review the code: Check programs/ to see exactly what was executed. The generated code shows the precise parameters used.

Ask for clarification: "Why did you use those parameter values?" or "Explain what that code does."

Try a different approach: Rephrase your request with more specific guidance: "Use a two-compartment model instead" or "Exclude subjects with missing doses."

I don't understand the output

Ask the AI to explain: "What does this AUC value mean?" or "Explain the diagnostic plot."

Search the docs: Ask "Search the Pumas docs for VPC" to find relevant documentation.

Request simpler output: "Show me just the key parameters" or "Summarize the results in plain language."

How do I redo or modify something?

Re-run from code: Find the script in programs/ and modify it directly, then run in Julia.

Ask for modification: "Redo that analysis but exclude subject 5" or "Refit with FOCE instead of FO."

Start fresh: "Clear the workspace and start over" if you want a clean slate.