Platform workflow

Use Rhesis from Claude Code, Cursor, or any compatible AI interface — without the Rhesis web UI.

The Rhesis agent skill (rhesis) packages platform knowledge into one portable skill file: explore endpoints, design test suites, generate and run tests, and analyze results. For building a test foundation from a spec first, see the spec workflow — same install, same skill.

This is different from Rhesis’s inbound MCP connector (where the platform imports content from Notion, GitHub, or Jira). Here, an external AI agent calls into Rhesis to drive the testing workflow.

Prerequisites

A Rhesis account at app.rhesis.ai (or a self-hosted backend)
An API token — generate one at app.rhesis.ai/tokens

Install in Claude Code

The plugin carries both the skill and the MCP server configuration, so it is the only install step. Do not also run npx skills add — that installs the skill a second time from a different source, and one copy silently shadows the other.

Step 1: Add the marketplace and install the plugin:

code.txt
/plugin marketplace add rhesis-ai/skills
/plugin install rhesis@rhesis-ai

Step 2: The install prompts for your API token and stores it in your OS keychain, so there is nothing to place by hand. Generate a token at app.rhesis.ai/tokens .

If you skipped the prompt, set it later with:

code.txt
/plugin configure rhesis@rhesis-ai

The server also reads RHESIS_API_KEY when the prompted value is unset, which suits CI and self-hosted setups that manage secrets elsewhere. Either export it, or put it in the env block of ~/.claude/settings.json so it applies to every session without touching your shell profile:

~/.claude/settings.json
{
  "env": {
    "RHESIS_API_KEY": "rhs_your_token_here"
  }
}

Either way the token is read at session start, so a running session will not pick up a new one.

Step 3: Restart Claude Code, then run /mcp. The plugin’s server is listed under Built-in MCPs, named with a plugin: prefix rather than plain rhesis, with a tool count after it:

code.txt
plugin:rhesis:rhesis · ✔ connected · 52 tools

That line is the only confirmation that matters. The skill on its own does nothing — every platform operation it performs is a call to this server, so an installed skill with no connected server cannot explore an endpoint, create anything, or run a test.

If /mcp asks you to authenticate a connector named “Rhesis AI”, the plugin’s server is not connected. That is a separate claude.ai cloud connector using OAuth, and the skill will offer it when the plugin’s own server is missing. Do not authenticate it. Fix the plugin server instead: confirm RHESIS_API_KEY is set, restart, and check /mcp again. When the plugin server is connected, that connector correctly stays under “unused connectors”.

Self-hosted backend:

code.txt
export RHESIS_MCP_URL=http://localhost:8080/mcp/
export RHESIS_API_KEY=your_local_token

Install in other agents

For Cursor, Codex, Gemini CLI, and 40+ other AI interfaces, the skill and the MCP server are two separate installs.

Step 1 — the skill. The CLI detects your installed agents and asks where to place it. Add -g for a global install, or omit it for a project-level install.

code.txt
npx skills add rhesis-ai/skills -g

# Install only for selected agents
npx skills add rhesis-ai/skills -a cursor -a codex -g

# Preview install targets without writing files
npx skills add rhesis-ai/skills --list

Step 2 — the MCP server. npx skills installs the skill instructions only, and the skill cannot do anything without the server. Configure it for your agent below.

Install in Cursor

Connect the MCP server

Add the following to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

.cursor/mcp.json
{
  "mcpServers": {
    "rhesis": {
      "url": "https://api.rhesis.ai/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_RHESIS_API_KEY"
      }
    }
  }
}

Replace YOUR_RHESIS_API_KEY with your actual token. Restart Cursor after editing.

For self-hosted backends, replace https://api.rhesis.ai/mcp/ with http://localhost:8080/mcp/.

Install the skill

Use the universal installer:

code.txt
npx skills add rhesis-ai/skills -a cursor -g

Cursor loads the skill automatically on the next session. If you prefer a project-level install, omit -g and run the command from the project where the skill should be available.

Usage

Once installed, interact with your AI interface naturally:


"I want to test my travel chatbot. The endpoint is called 'travel-agent-v2'."

The skill guides the full workflow:

Discover — explores what your endpoint can do (Quick or Comprehensive mode)
Plan — proposes a test suite with requirements, test sets, and metrics
Review — waits for your approval before creating anything
Create — builds entities on the platform following the approved plan
Execute — runs tests when you confirm
Analyze — presents pass/fail summary, failure patterns, and links

You can also use it for direct operations:


"List my existing test sets"
"Improve the Safety Compliance metric — make the threshold stricter"
"Compare my last two test runs"
"Link the Accuracy metric to the Provides Accurate Information requirement"

Spec workflow

If you have a Product Requirements Document (PRD) or product spec and want a test foundation before running tests, paste your spec in chat — the skill routes to the spec workflow. After approval it creates requirements, metrics, tags, and test sets via MCP; then continue here to execute and analyze.

Agent skill vs. native Architect

The Rhesis platform has a built-in Architect agent with a web chat UI. This skill is a complement, not a replacement:

	Native Architect	Rhesis agent skill
Access	Rhesis web UI	Your existing AI interface
Plan tracking	Structured plan with progress bar	Conversational, host agent context
Confirmation guard	Accept/Change UI, auto-approve toggle	Host agent’s native confirmation
Write guard	Structural enforcement	Instructional guidance only
Mode transitions	Formal phases with events	Informal, guided by skill

Use the native Architect for maximum structural control. Use this skill when you want to work within Claude Code or Cursor without switching context.

→ See Workflow for a full breakdown of the native Architect’s phases and UI indicators.

Troubleshooting

MCP server not connecting

Verify your API token is valid and has not expired — regenerate at app.rhesis.ai/tokens
Test connectivity: curl -H "Authorization: Bearer $RHESIS_API_KEY" https://api.rhesis.ai/mcp/
In Cursor, restart the IDE after editing .cursor/mcp.json

Skill not activating (Cursor)

Run npx skills list and confirm rhesis appears at the expected install path
Verify ~/.cursor/skills/rhesis/SKILL.md exists
Try explicitly invoking: type /rhesis in the chat

Claude Code: the skill asks you to authenticate a “Rhesis AI” connector

The plugin’s MCP server is not connected, so the skill is falling back to the claude.ai cloud connector, which uses OAuth instead of your API token. Do not authenticate it. Run /mcp and check for plugin:rhesis:rhesis:

Not listed at all — the plugin is not installed or not enabled. Check claude plugin list.
Listed but failed — RHESIS_API_KEY is unset or invalid. Set it (see step 2 above) and restart. Environment variables are read at session start, so a running session will not pick up a new one.

Claude Code: rhesis appears twice, or edits to the skill have no effect

The skill is installed from two sources, usually because npx skills add was run alongside the plugin. One shadows the other, and they update through different channels. Remove the standalone copy and keep the plugin:

code.txt
rm ~/.claude/skills/rhesis

This leaves ~/.agents/skills/rhesis in place, so Cursor and Codex keep working.

Source

The skill source lives at skills/rhesis/ in the Rhesis repository. Reference files covering MCP tools, OData query patterns, exploration strategies, and result analysis are in skills/rhesis/references/.

See also the spec workflow (skills/rhesis/references/prd/) for building a test foundation from a spec.