Skip to main content

Connect AI Agents to Your RC Account (Voyager MCP)

Level: Intermediate · Time: 10 min · Category: How-to

Tags: MCP · Voyager · Claude Code · OpenCode · VS Code

The Voyager portal runs an MCP server, voyager-mcp, that gives an AI agent read access to your Research Computing account. Once connected, an agent such as Claude Code, OpenCode, or VS Code agent mode can answer questions like "why did job 4821337 fail?" or "which of my GPU jobs are underusing their GPUs?" from live data. It can also write a batch script that matches your allocations and the hardware that exists, and it can search this documentation site. With the workflow capability, it can design and deploy Kubernetes workflows for you.

MCP (Model Context Protocol) is the open standard AI agents use to call external tools. Each agent connection you create in Voyager has its own token. That token acts as you, limited to the capabilities you select when you create it.

Before you start
  • A Voyager account. Any account works. Which tools you get depends on the services you hold (an HPC cluster account, Kubernetes access, and so on).
  • The ASU network or the SSLVPN. voyager.rc.asu.edu only resolves on the ASU network, so the computer running your agent must be on campus or connected to the VPN.
  • An MCP client that supports remote (HTTP) servers with a custom Authorization header. Claude Code, OpenCode, and VS Code all do. Clients that can only connect through an OAuth sign-in cannot use voyager-mcp yet.
Tool results go to your agent's model

voyager-mcp sends the data each tool returns to the model your agent is using. That data includes job names, paths, and account details. If that model is hosted by an outside company, the data is sent to that company. To keep it on Research Computing hardware, run your agent against the RC models; see Set up OpenCode. Check the ASU Data Classification Tool before connecting an agent to sensitive research data.

How it works​

Endpointhttps://voyager.rc.asu.edu/api/mcp
TransportStreamable HTTP (stateless, JSON responses)
AuthenticationAuthorization: Bearer rcmcp_…, a token from your agent connection
ScopeYour own account only. No tool takes a username, and other users' jobs read as "not found".
Clusterssol (the default) and phoenix (phx also works)
Rate limit20 tool calls per minute per connection

1. Create an agent connection​

  1. Sign in to the Voyager portal, open your profile, and select the Keys tab. The former MCP tab is now part of Keys.
  2. Click New agent connection. If you have none yet, click Create your first connection instead.
  3. Fill in the dialog:
    • Name: what this connection is for, such as Work laptop or Claude Code on Sol. Use one connection per agent or computer, so you can revoke one without breaking the others.
    • Capabilities: choose what the agent may access; see the table below. My jobs & GPU efficiency and My account & allocations are selected by default.
    • Connection lifetime: 30 days, 90 days (recommended), 180 days, or 1 year (max).
  4. Click Create connection.
  5. Copy the token. It starts with rcmcp_ and is shown only once. The same dialog shows ready-to-paste setup for Claude Code, a .mcp.json file, and OpenCode, with your token already filled in. Click I saved the token when you are done.
Treat the token like a password

Anyone holding the token can use the capabilities you granted, as you, until it expires or you revoke it. Keep it out of Git repositories, shared notebooks, and screenshots. Voyager stores only a hash of the token, so it cannot show it to you again. If you lose it, revoke the connection and create a new one.

A few things to know:

  • You can have up to 10 active connections.
  • You cannot change a connection's capabilities or extend its lifetime. Create a new connection, then revoke the old one.
  • Voyager emails you whenever a new agent connection is added to your account. If you did not create it, revoke it right away and contact us.

Capabilities​

Every capability except the two marked writes is read-only. Capabilities your account cannot use are listed under the checkboxes as Not available on your account, with what each one needs.

CapabilityWhat the agent can see or doNeeds
My jobs & GPU efficiencyYour running and pending jobs, any one job in detail (state, exit code, the reason it ended, requested and allocated resources, steps), job history summaries, live GPU utilization, the GPU job archive, fix-it suggestions for low-utilization GPU jobs, and your login-node usageHPC account
My account & allocationsYour profile (groups, sponsor, department, services), plus the Slurm accounts and QOS levels you can submit underAny account; allocations need an HPC account
My storage & quotasHome, scratch, and project quotas and usage, and scratch directories nearing expiryHPC account
Software catalogSearch the module catalog on Sol and PhoenixAny account
Job templates & how-tosJob script templates (single-GPU training, CPU job arrays, interactive GPU sessions), a pending-job guide, and each cluster's node hardwareHPC account
RC documentationSearch and read this documentation siteAny account
My workflows & KubernetesThe workflow template catalog, workflow validation, your saved workflows and run history, and what is running in your Kubernetes namespaceHPC account or Kubernetes access
Build & deploy workflows (writes)Save workflow designs as drafts, and deploy saved Kubernetes workflows to your namespaceHPC account or Kubernetes access
My Jetstream2 cloudYour Jetstream2 instances, volumes, floating IPs, quota, and service-unit balanceA Jetstream2 application credential, connected under the Jetstream2 tab
My Sim workflows / Build Sim workflows (writes)Read, build, and revise workflows and knowledge bases in your Sim Studio workspaceA Sim API key, connected under Keys › Cluster tokens and outside services. Shown only where the Sim integration is enabled.
Job submissionSubmit Slurm jobs as you. Shown as Coming soon; it cannot be granted yet.

2. Add the connection to your agent​

Use the endpoint https://voyager.rc.asu.edu/api/mcp and send the token in an Authorization: Bearer header. Each example below reads the token from an environment variable, so it does not end up in a config file or your shell history.

Read the token from a prompt, then register the server:

read -rs VOYAGER_MCP_TOKEN   # paste the token, then press Enter (nothing is echoed)
claude mcp add --transport http --scope user voyager-mcp https://voyager.rc.asu.edu/api/mcp \
  --header "Authorization: Bearer $VOYAGER_MCP_TOKEN"
unset VOYAGER_MCP_TOKEN

--scope user makes the server available in every project. Leave it out to add the server to the current project only. Confirm the connection with claude mcp list, or run /mcp inside a Claude Code session.

The .mcp.json snippet in Voyager's token dialog is the same server written as a project file. If you keep .mcp.json in a repository, replace the token with ${VOYAGER_MCP_TOKEN}. Claude Code expands environment variables in this file, so the token itself never gets committed:

.mcp.json
{
  "mcpServers": {
    "voyager-mcp": {
      "type": "http",
      "url": "https://voyager.rc.asu.edu/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VOYAGER_MCP_TOKEN}"
      }
    }
  }
}

Send a first request​

Start your agent and ask something that needs your account. For example:

Use the voyager-mcp tools: what Slurm accounts and QOS levels can I submit under on Sol,
and do I have any jobs running right now?

Your agent should call get_my_allocations and get_my_active_jobs, and it may ask you to approve each call first. If the agent answers without calling a tool, check that the server shows as connected (see Troubleshooting).

What to ask​

AskTools the agent uses
"Why did job 4821337 fail?"get_my_job (state, exit code, signal, out-of-memory or timeout)
"Are any of my GPU jobs wasting their GPUs? How do I fix them?"get_my_gpu_efficiency, get_gpu_job_suggestions
"Write me a single-GPU PyTorch training script for Sol."list_job_templates, get_job_template, get_my_allocations, get_cluster_nodes, search_software, search_docs
"Why is my job still pending?"get_my_job, the pending-job guide in get_job_template, get_cluster_nodes
"Am I close to my scratch quota? Is anything about to expire?"get_my_storage
"How many GPU hours did I use last month, and how many jobs failed?"get_my_job_history
"Is GROMACS installed on Phoenix? Which versions?"search_software
"Am I running heavy work on a login node?"get_my_login_node_usage
"Set up JupyterLab on Gaudi in my namespace, but don't deploy it yet."list_workflow_templates, get_workflow_template, validate_workflow_graph, save_workflow_draft

The agent writes job scripts for you to review and submit with sbatch. It cannot submit Slurm jobs for you yet.

Tools​

Your agent sees only the tools your connection's capabilities allow and your account holds. Everything returns your own data unless noted.

CapabilityToolReturns
My jobs & GPU efficiencyget_my_active_jobsRunning and pending jobs on one cluster (live scheduler state)
get_my_jobOne job in detail, running or finished: final state and reason, exit code and signal, requested vs. allocated resources, timing, nodes, working directory, step states
get_my_job_historyJob counts by final state, CPU and GPU hours, and a daily series for the last 1–365 days (default 7) across both clusters
get_my_gpu_efficiencyLive GPU utilization of running GPU jobs over a 4 h, 24 h, 7 d, or 30 d window, with the policy thresholds and each job's tier
get_my_gpu_historyPer-job archive of finished GPU jobs: utilization, memory, idle GPU-hours, energy. Paginated.
get_gpu_job_suggestionsAdvice for 1–50 running GPU jobs flagged for low utilization: likely causes and concrete fixes
get_my_login_node_usageCPU, memory, and "badness" per login node
My account & allocationsget_my_account_profileDisplay name, groups, sponsor, department, shell, services
get_my_allocationsSlurm accounts, allowed QOS levels, default account
My storage & quotasget_my_storageHome and scratch usage against quota, project and archive allocations, scratch nearing expiry (GB)
Software catalogsearch_softwareMatching modules and versions on Sol or Phoenix
Job templates & how-toslist_job_templates / get_job_templateJob script templates with parameters and known pitfalls
get_cluster_nodesEach distinct node shape (CPUs, memory, GPU model and count, features), how many exist, and their states; filter by partition
RC documentationsearch_docs / get_doc_page / list_doc_pagesSearch results, full pages, and the table of contents of this site
My workflows & Kuberneteslist_workflow_templates / get_workflow_templateThe workflow catalog (FastFold, JupyterLab on Gaudi, vLLM on Gaudi, and more) and each template's graph
validate_workflow_graphChecks a workflow without saving it: issues per node, the compiled Kubernetes manifest or Slurm script, and portability to the other scheduler
list_my_workflows / get_my_workflowYour saved workflow designs
get_my_workflow_runsYour last 50 workflow runs and their outcomes
get_my_k8s_workloadsDeployments, jobs, pods, and volume claims in your namespace right now
Build & deploy workflowssave_workflow_draftSaves a design as a draft. Nothing runs.
deploy_workflowDeploys a saved Kubernetes workflow to your namespace
My Jetstream2 cloudget_my_cloud_instances / get_my_cloud_storage / get_my_cloud_quota / get_my_cloud_allocationsInstances, volumes and floating IPs, quota, and SU balance
My Sim workflows / Build Sim workflowslist_my_sim_workflows, get_sim_workflow, create_sim_workflow, revise_sim_workflow, and othersYour Sim Studio workflows, runs, blocks, and knowledge bases

Tools that change things​

Most tools only read. Two workflow tools change things, and the server marks both as destructive, so most clients ask you to approve each call:

  • save_workflow_draft saves a design you can open on the visual canvas under Workflows & Apps. Without an id it creates a new design, which is always safe. With an id it overwrites that design, and the old version cannot be recovered.
  • deploy_workflow compiles a saved workflow and applies it to your Kubernetes namespace right away. It uses your quota. Every deploy appears in your run history and the audit log. Workflows that target Slurm can be built and validated, but not deployed yet.

The server tells agents to deploy only when you have clearly asked them to, and to save a draft otherwise. Say which one you want in your prompt.

The Build Sim workflows capability can also create, revise, rename, and permanently delete workflows and knowledge bases in your Sim workspace.

Limits and data freshness​

  • Rate limit: 20 tool calls per minute per connection token, shared by every client using that token. A refused call returns an error with error.data.retryAfterSeconds and a Retry-After header; good agents wait that long. Give each agent its own connection.
  • Active jobs come from the live scheduler. A finished job disappears from get_my_active_jobs; ask about it with get_my_job.
  • Job history comes from accounting data, which lags the scheduler by a few minutes.
  • The GPU archive (get_my_gpu_history) starts in late July 2026. For totals, use get_my_job_history.
  • Storage readings are cached and refreshed when they are over an hour old, so a call can take about 15 seconds. A value of unknown means no reading could be taken, not zero.
  • Documentation search covers this site and refreshes every few hours.

Manage your connections​

Every connection is listed under Agent connections on the Keys tab. Each row shows:

  • the name you gave it, and the client name and version the agent reported
  • its status: Used … ago, Never used, Expires in N days, Expired, Revoked, or Disabled by account status
  • its capabilities, a 7-day activity sparkline, and its call and failure counts

Details shows the token's first characters, the created and expiry dates, and every tool the connection can call.

The Agent activity sub-tab lists each tool call your agents made: the tool, the connection, the status (ok, upstream error, denied, rate limited, invalid args), the duration, and when it ran. Voyager records which tool ran and the names of its arguments, never their values.

  • Revoke stops a connection immediately and cannot be undone. Revoke any connection whose token may have leaked.
  • Delete appears after a connection is revoked or has expired. It removes the connection and its activity history from the list.
  • If your account is locked or archived, its connections are suspended. They resume if the account is restored.

Troubleshooting​

Error or symptomWhat it means
Missing bearer token…The client is not sending the Authorization: Bearer rcmcp_… header. Check the header name and that the environment variable is set in the shell that starts your agent.
Unknown token…The token is mistyped or truncated. Copy it again, or create a new connection.
This connection was revoked… / This connection's token has expired…Create a new connection in Keys.
This connection is disabled because of the account's status…Your account is locked or archived. Contact us.
The connection fails, or a browser shows a "VPN required" pageYou are off the ASU network. Connect to the SSLVPN.
Unknown tool: …The connection does not include the capability for that tool, or your account does not hold the service it needs. Create a connection with the capability.
Rate limit exceeded (20 calls/minute per connection token)…Wait the number of seconds in the message. Ask the agent to work through results one call at a time.
Jetstream2 tools say no credential is connectedAdd an OpenStack application credential under the Jetstream2 tab.
No Sim tools appearConnect a Sim API key under Keys › Cluster tokens and outside services.
The agent answers without using any toolsCheck the server is connected (claude mcp list, /mcp, or your client's MCP panel), then name the tools in your prompt: "Use the voyager-mcp tools to…"