Agentic interface (MCP server)¶

Purdue AF provides a remote MCP (Model Context Protocol) server that lets you manage your Analysis Facility session from any MCP-capable AI agent — Claude Code, Codex, Cursor, and others. You can control the AF in natural language: start and stop your session, check whether the facility is healthy, and inspect your Dask clusters, storage usage, and logs.

Agents inside an AF session are ready to use; agents on your own machine need a token and a one-time setup.

Inside an AF session¶

Nothing to set up. claude, codex and opencode are on PATH in any terminal, the Claude Code and Codex extensions are installed in the VS Code interface, and all three are already connected to the MCP server as you — no token, re-registered on every session start.

A short platform context is installed too: the facility's rules and recommendations (storage volumes and quotas, where environments may live, scale-out limits, GPU options) written into the file each agent reads automatically at startup. You do not need to invoke anything — an agent in a session already knows, for example, that pixi install will be refused under /home and that /work is invisible to Slurm workers.

For Claude Code and Codex the context goes into a file you own, and only the block between the PURDUE AF — managed markers belongs to the facility — anything you write outside it is preserved. The block is refreshed on every session start.

opencode is different: nothing of yours is touched at all. Both the context and the MCP server live in a facility-owned config layer, so the context reaches opencode even in a project that has its own AGENTS.md (its own lookup stops at the first match it finds, which a project file would win).

Run claude, codex or opencode and ask for what you want. You still sign in to the agent with your own Anthropic, OpenAI or other provider account; the AF ships no model credentials.

AI in JupyterLab¶

The same agents are also available as a chat panel inside JupyterLab, via Jupyter AI. Nothing to enable — open the chat from the left sidebar and @-mention Claude, Codex or OpenCode.

They are the same agents as in the terminal, using the same login: if claude works in your terminal, the Claude persona works in the chat. They can read and write files, run commands, and edit the notebook you have open, asking for approval before each. The AF MCP server is connected for them too, so you can ask about your session, Dask clusters, storage and logs without leaving the notebook.

The platform context reaches them by the same route it reaches your terminal — each persona runs the agent's own binary with its own settings, so the files in the table above apply unchanged. There is nothing extra to install for the chat.

Connecting from your own machine¶

1. Obtain a JupyterHub API token at https://cms.geddes.rcac.purdue.edu/hub/token.

2. Add the server in your agent's MCP settings. Most agents accept this configuration:

   {
     "mcpServers": {
       "purdue-af": {
         "type": "http",
         "url": "https://cms.geddes.rcac.purdue.edu/services/agentic-interface/mcp",
         "headers": { "Authorization": "Bearer YOUR_TOKEN" }
       }
     }
   }
   

   Where this goes depends on your agent — a config file, a settings panel, or a CLI command (claude mcp add, codex mcp add, …) — but the URL and header are always the same. If your agent expands environment variables in its config, use Bearer ${JUPYTERHUB_TOKEN} instead of pasting the token.

mkdir -p ~/.config/purdue-af && chmod 700 ~/.config/purdue-af
printf '%s' '<your-api-token>' > ~/.config/purdue-af/token
chmod 600 ~/.config/purdue-af/token

claude mcp add --scope user --transport http purdue-af-agentic-interface \
  https://cms.geddes.rcac.purdue.edu/services/agentic-interface/mcp \
  --header "Authorization: Bearer $(cat ~/.config/purdue-af/token)"

Installing the skill (recommended)¶

The MCP server is self-describing, but agents work noticeably better with the accompanying skill — a Markdown playbook that teaches the agent the AF workflows (how to launch a session, which tools to call in what order). It lives in the Purdue AF repository: .claude/skills/purdue-af-agentic-interface/SKILL.md

For Claude Code, install it with:

mkdir -p ~/.claude/skills/purdue-af-agentic-interface
curl -fsSL -o ~/.claude/skills/purdue-af-agentic-interface/SKILL.md \
  https://raw.githubusercontent.com/PurdueAF/purdue-af/main/.claude/skills/purdue-af-agentic-interface/SKILL.md

The skill then activates automatically whenever you mention your Purdue AF session, Dask clusters, or AF logs/storage.

For other agents, copy the same file's contents into whatever your agent uses for persistent instructions — ~/.codex/AGENTS.md for Codex, ~/.config/opencode/AGENTS.md for opencode, Customize → Rules for Cursor. It is plain Markdown with no Claude-specific content beyond the front-matter header.

What you can do¶

Your username and session are resolved automatically, so you can simply ask in plain language, for example:

• "Start my AF session" (optionally: "…with 32 CPUs and the VS Code interface")
• "How much home and work storage am I using?"
• "List my Dask clusters" / "scale <name> to 10 workers"
• "Create a Dask cluster" — the agent walks you through multiple-choice questions (backend, worker environment, worker size, and worker count) before creating it
• "Show the last 30 minutes of error logs from my notebook"
• "Is the AF healthy?" — what is affecting the facility, if anything, and for how long

The available tools cover:

• Facility health — a summary of anything currently affecting the facility: access, storage, scale-out, and the software environment.
• Session lifecycle — check status, list available resource profiles, start / stop / restart the session, and wait until it is ready. When starting, the agent asks you (as multiple-choice questions) which profile and resource options — interface, CPU, memory — to use, unless you ask for the defaults.
• Storage — home and work directory quota usage.
• Dask clusters — list, create (Kubernetes or Slurm/Hammer), inspect, check worker counts and CPU/memory usage, scale, and shut down your Dask Gateway clusters on either gateway (k8s or slurm).
• Logs — query your JupyterLab / VS Code server logs and Dask worker and scheduler logs, with time ranges and filters.

The server also exposes one invocable workflow prompt, create_cluster, which walks the agent through the four cluster questions when its client cannot ask them itself. In Claude Code it appears as /mcp__purdue-af-agentic-interface__create_cluster.

Troubleshooting¶

Failures are self-describing: a failing tool result (which the agent relays to you) says what was attempted, why it failed, and what to do next. If the connection itself is refused — the agent shows the server as failed or needing authentication — the server's response carries an error and a hint with the same information; ask the agent for it, or check your MCP client's server status.