Supervaize Access

Repository: runwaize_skills/supervaize_access

This skill is for Supervaize users (customers). Install it so your AI assistant (Cursor, Claude CLI, Codex, etc.) can manage your Supervaize workspace with your API key: list and edit agents, create and manage missions, and use case/step and human-in-the-loop (HITL) via the REST API and MCP server. Permissions follow your team membership and role (read-only users cannot perform write operations).

:::info When to use Use this skill when the user wants a chatbot or IDE agent to operate against an existing Supervaize workspace — registering with an API key, creating missions, or inspecting cases and steps via the REST API and MCP. :::

This is a separate skill from Supervaizer Integration (which adds Supervaizer instrumentation to a custom agent). Supervaize Access uses REST API and MCP only from a chatbot/IDE after credentials and workspace are known.

Overview (REST + MCP)

Surface	URL / scope	Capabilities
REST API	`{base_url}/w/{team_slug}/api/v1/`	Full CRUD for agents and missions. Auth: `Api-Key: <key>`.
MCP server	`{base_url}/api/mcp/` (root-level; not under `/w/{team_slug}/`)	Case/step reporting and HITL. Same API key or Bearer (e.g. n8n). Tools: `report_case_start`, `report_case_step`, `request_human_input`, `get_case_status`, `report_case_status`, `register_agent_parameters`. All require `team_slug` in arguments.

Permissions: The key’s user must be a member of the workspace. Read-only members can call read-only endpoints/tools only; write operations return a permission error.

Current gaps: No REST CRUD with API key for jobs (create, list, detail, start, stop) or cases (list/detail, step resolution). Use the Studio UI or session-based flows for those. Case creation and step reporting are available via MCP.

Getting an API key

Log in to Supervaize Studio.
Open your user/account settings (or the API keys section in your workspace).
Create a User API key and copy the key value (shown once).
The key is scoped to your user; you can only access workspaces (teams) you are a member of.

REST API (agents and missions)

Base URL: https://<your-studio>/w/<team_slug>/api/v1/
Authentication: Api-Key: <your-key> (or Authorization: Api-Key <your-key>).

Agents: GET .../agents/ (list), POST .../agents/ (create), GET .../agents/{id}/, GET .../agents/by-slug/{slug}/, PUT / PATCH / DELETE .../agents/{id}/.

Missions: GET .../missions/ (list), POST .../missions/ (create), GET / PUT / PATCH / DELETE .../missions/{id}/.

For request/response fields, see the OpenAPI schema at {base_url}/api/doc or {base_url}/api/doc/swagger-ui/.

MCP server (cases, steps, HITL)

Endpoint: https://<your-studio>/api/mcp/ (root-level; no /w/... in path).
Authentication: Same Api-Key header, or Bearer token for n8n-linked workflows.

Tool	Purpose
`report_case_start`	Create a case for a job (job_id, execution_id, team_slug)
`report_case_step`	Create or update a case step
`request_human_input`	Create a human-in-the-loop step (case set to awaiting)
`get_case_status`	Get case status by execution_id
`report_case_status`	Update case status (e.g. completed, failed)
`register_agent_parameters`	Register n8n workflow parameters for an agent

Use the MCP protocol (initialize, tools/list, tools/call) over HTTP. For full tool schemas and required arguments, see reference.md in the supervaize_access skill in runwaize_skills.

Install

Install the skill from the runwaize_skills repo so your AI agent can operate against your workspace.

Cursor: Copy the supervaize_access folder into your project .cursor/skills/ or user skills folder.
Claude Code: Copy or symlink the same folder to ~/.claude/skills/supervaize_access/ (or your project’s .claude/skills/).

Setup

Required environment variables

export SUPERVAIZE_API_KEY=...
export SUPERVAIZE_WORKSPACE_ID=team_1
export SUPERVAIZE_API_URL=https://app.supervaize.com

Register the session first

Before running commands, validate credentials and workspace:

python scripts/supervaize_access_helper.py register-to-supervaize --pretty

This stores a local profile for later commands.

What this skill enables

The skill maps natural-language phrases to helper commands:

Phrase	Command
"Register to supervaize"	`register-to-supervaize`
"Create a mission"	`create-mission`
"Start a job"	`start-job` (returns limitation; see below)
"View case(s) / step(s)"	`view-cases-steps`
"Show the missions for this agent"	`show-missions-for-agent`
"What is the status of the jobs for this agent"	`job-status-for-agent`

Backends and limits

The helper uses REST API and MCP only:

Backend	Use for
Supervaize SaaS REST API	Teams, agents, missions, controller events (`ctrl-events`)
Supervaize MCP endpoint (`{base_url}/api/mcp/`)	MCP tools: `get_case_status`, `report_case_start`, `report_case_step`, `request_human_input`, `report_case_status`, `register_agent_parameters`

Current public API limitation: no public generic /jobs or /cases//steps REST endpoints in the spec. Job start is not exposed via REST or MCP. When a command cannot be fulfilled from the current surfaces, the helper returns a structured explanation (e.g. for start-job) with suggestions.

Command details

`register-to-supervaize`

Use first. Validates API key + workspace and saves a local profile.

`create-mission`

Creates a mission through the SaaS REST API.

python scripts/supervaize_access_helper.py create-mission \
  --name "Outbound Follow-up" \
  --description "Q1 sales follow-up campaign" \
  --status draft \
  --pretty

`start-job`

Job start is not exposed via the public REST API or MCP. The command returns a structured limitation and suggestions (e.g. use the Studio UI or the Supervaizer Integration skill for agent-side job starts).

python scripts/supervaize_access_helper.py start-job --pretty

`view-cases-steps`

--backend api: reads ctrl-events and reconstructs case/step activity (best effort).
--backend mcp: calls get_case_status for a known execution_id.

python scripts/supervaize_access_helper.py view-cases-steps --backend api --job-id 01H... --pretty
python scripts/supervaize_access_helper.py view-cases-steps --backend mcp --execution-id n8n-exec-123 --pretty

`show-missions-for-agent`

Tries REST API first. If mission objects do not expose agent linkage, returns a structured limitation and suggests providing internal endpoint access or another source that maps agent ↔ mission.

`job-status-for-agent`

Uses ctrl-events to aggregate job lifecycle events (best effort). Accuracy depends on agent identifiers being present in event source/details.

References

REST paths and MCP tool args: reference.md in the supervaize_access skill.
Supervaizer Integration — add controller instrumentation to a custom Python agent.
n8n Integration — use n8n workflows as agents.

Overview (REST + MCP)​

Getting an API key​

REST API (agents and missions)​

MCP server (cases, steps, HITL)​

Install​

Setup​

Required environment variables​

Register the session first​

What this skill enables​

Backends and limits​

Command details​

register-to-supervaize​

create-mission​

start-job​

view-cases-steps​

show-missions-for-agent​

job-status-for-agent​

References​