scenario-team-admin — Claude Code skill: what it does, how to install

---
name: scenario-team-admin
description: "Use when administering a Scenario team from an agent through MCP: restricting which models a team or project can run (model access control, allowlist, blocklist), inviting or removing team and project members, changing roles, capping a member's Creative Unit spend, creating or deleting projects, auditing API keys and their roles or scopes, or attributing consumption per user or model. Keywords: governance, model control, consumption cap, spend limit, API key hygiene, team admin, enterprise."
license: MIT
---

# Scenario Team Administration

## Overview

Enterprise teams govern Scenario from the same agent that generates on it: which models anyone may
run, who is on the team and in which projects, how much each member may spend, and which API keys
exist with which roles. Every tool here is catalog-only: `scenario_tools_search` returns the schema
and lane, and `scenario_tool_execute_read` / `write` / `delete` runs it with `{name, parameters}`,
scope ids inside `parameters` (see the `scenario` skill). Two facts decide most failures before any
argument does: the identity behind the call, since team-level writes need a human team admin over
OAuth and refuse API keys, and the list mode the team runs, since the same model-access edit means
the opposite thing in blocklist and allowlist mode. `teams_list` already tells you both: each team
row carries `modelsManagement`, its model lists, `plan`, and `context.userRole`. A credential that
reaches one team and one project has its scope; more than one is a stop-and-list, per the `scenario`
skill. If a sibling skill named here is missing from your available skills, ask the user to install
it (`npx skills add scenario-labs/skills --skill <name>`); unattended, proceed from tool schemas and
flag the gap.

## Quick reference

| Task                 | Tool                                                                | Lane                       | Notes                                                                                |
| -------------------- | ------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------ |
| Read model access    | `model_access_get`                                                  | read                       | Mode plus the team's active list; `project_id` adds that project's list alongside it |
| Change model access  | `model_access_update`                                               | write                      | `level` `team` or `project`; exactly one of `add_models`, `remove_models`            |
| Team roster          | `team_members_list`                                                 | read                       | Members and pending invitations                                                      |
| Invite               | `team_members_add`                                                  | write                      | 1 to 32 `emails`, `role`, optional `project_ids` joined on acceptance                |
| Roles and spend caps | `team_members_update`                                               | write                      | `member_ids` 1 to 32; `role` and/or `max_consumption`                                |
| Remove from the team | `team_members_remove`                                               | delete                     | Also withdraws invitations; access ends immediately                                  |
| Project roster       | `project_members_list`, `_add`, `_update`, `_remove`                | read, write, delete        | Roles `admin` (Owner), `editor` (Contributor), `reader` (Viewer)                     |
| API keys             | `api_keys_list`, `api_key_get`, `api_key_update`, `api_key_delete`  | read, write, delete        | Project scope; `api_key_create` returns the portal link and nothing else             |
| Projects             | `project_get`, `project_create`, `project_update`, `project_delete` | read, write, write, delete | Create needs a team admin over OAuth and counts against the plan's project limit     |
| Who spent what       | `usage`                                                             | read (default tools)       | Per-user and per-model consumption in the default response                           |

## Model access: read the mode before editing

`model_access_get` returns `models_management` and only the mode's active list; the inactive stored
list is never surfaced. In blocklist mode (the default) every catalog model is available except
those on the team or project blocklist, and the two lists block as a union. In allowlist mode a
model is available only when it sits on both the team and the project allowlist; a project with an
empty allowlist denies every model, and a project with no allowlist configured falls back to the
team list.

`model_access_update` edits whichever list the mode makes active, so `add_models` blocks in
blocklist mode and allows in allowlist mode: read the mode first, every time. Switching the mode is
not available through MCP; it lives in the web app's team settings, so locking a team down to an
approved set starts with the user flipping to allowlist there. Unattended, that switch is a
stop-and-report: log that the lock waits on it and the exact calls that follow, and take the
blocklist-safe partial (blocking the named unwanted models at project level), saying that other
projects stay open. Narrowing a list the credential can edit is in scope when the task states the
target set: `remove_models` runs after the adds succeed, so the list never ends empty.
`level: "team"` needs a team admin over OAuth, and the server refuses API keys on that endpoint.
`level: "project"` takes the projects to edit in `projects` (1 to 200) and needs the admin role on
every one of them: one unauthorized project fails the whole request and nothing updates, and a
single-project key can only edit its own project's list. `project_id` on the call is tenant context
for OAuth sessions, never the target. In allowlist mode a project admin can add only models already
on the team allowlist (a project list narrows the catalog, never widens it), removing a base model
from a team allowlist cascade-removes the trained models built on it, and a team-level add validates
every id, one unknown id failing the whole call. `updated: false` means the diff was a no-op, not an
error. A blocked model disappears from what members can run, and the error a member sees when
running one anyway is a restriction, not moderation (see `scenario-moderation`).

## Members and spend caps

`team_members_update` takes `member_ids` from `team_members_list` and sets `role` (`admin` or
`member`), `max_consumption`, or both. The cap is in Creative Units over the current billing period:
a value of zero or more caps, `-1` is unlimited, and `null` clears the per-member override so the
team-wide default applies. Roles can be set by a team admin over OAuth or a team-scoped API key with
the `team.members.manage` scope; caps need a real team admin, and a key that tries is refused per
member. Demoting the last admin fails server-side. The bulk member tools process one row at a time
and report an outcome per member; a response with `status: "partial"` is finished by calling again
with its `remaining` list.

`team_members_add` invites 1 to 32 emails at `role` (default `member`) and joins them to
`project_ids` on acceptance; outcomes are `invited`, `failed`, or `skipped` with the reason (already
a member, already invited, seat limit reached). `project_id` on the call grants nothing. Like role
changes, inviting takes a team admin over OAuth or a team-scoped key with `team.members.manage`; a
project-scoped key gets a permission error. A pending invitation carries no member id, so its cap
waits for acceptance. `project_members_add` takes people already on the team, as user ids or emails
(emails need `team_id` to resolve), with a required project role.

Removal is the delete lane and immediate: `team_members_remove` ends the person's access everywhere
and withdraws pending invitations, `project_members_remove` leaves team membership and other
projects untouched. List first, confirm the exact names with the user, then remove; unattended,
remove only the members the task instructions name.

## API keys

`api_keys_list` and `api_key_get` are project-scoped and return each key's `id`, `api_key_id`, name,
status, scope, role, projects, and creation date, plus a `manage_keys_url`; team-scoped keys are not
attached to projects and never appear here, only in the portal. `api_key_update` changes a key's
`role` to `admin`, `editor`, `reader`, or a custom `;`-separated scope list (the reference's example
is `assets.read;models.run`); name, status, and usage limits are portal-only, and a limit takes an
Enterprise plan and a human admin. Creation is deliberately not an MCP operation: `api_key_create`
returns the portal link, the secret is shown once there, and it never passes through the
conversation (the `scenario` skill's rule on secrets holds here). `api_key_delete` takes the key as
`key_id` (either the `id` or the `api_key_id` from the listing), cannot be undone, needs a project
admin, and refuses the key the current session is authenticated with: list, confirm the exact key
with the user, then delete; unattended, delete only a key the task instructions name and exactly one
key matches.

## Projects

`projects_list` (default toolset) finds what exists; create only when nothing matches.
`project_create` takes `team_id`, `name`, and `privacy_mode`; a description needs a follow-up
`project_update`. It needs a human team admin over OAuth (API keys are refused) and counts against
the plan's project limit, which refuses the call once reached: report the limit, never delete a
project to make room. Pass the returned `project.id` as `project_id` from then on. In a team with no
projects, the API first creates a default project, which stays even when the call is refused: check
`projects_list` afterwards and offer to rename it with `project_update` rather than keep two
(unattended: report it, change nothing).

- **Privacy.** `privacy_mode: true`, on `project_create` or `project_update`, limits non-admin
  members to the assets and models they created; project and team admins still see everything.
  Turning it off shows every member everything: confirm with the user first; unattended, only when
  the task instructions say so.
- **Rename.** `project_update` changes only the fields passed: `name`, `description` (up to 2,000
  characters), `privacy_mode`, `avatar_asset_id`. Access, model lists, and credit caps live in the
  tools above or the web app.
- **Delete.** `project_delete` runs on the delete lane, is irreversible, and takes the project's
  models, generation records, API keys, and memory with it. Confirm the name and id from
  `project_get` first. It takes the target as `project_id`, and is refused while anyone but the
  caller holds a role on the project or a key is attached: report who remains and ask, and never
  remove a member or delete a key to unblock it without a separate confirmation of each. The creator
  joins as Admin by default (`auto_join`), which blocks a delete by anyone else. Unattended, delete
  only a project the task instructions name, when exactly one matches, and report a refusal and
  stop.

## Who spent what

`usage` is in the default toolset and returns a summary by default: headline CU totals, per-user
consumption, per-model CU and job counts sorted descending, and per-asset-kind counts, bounded by
`start_date` and `end_date` (ISO dates); `project_id` filters the figures, so a single-project
credential ranks spend inside that project, not across the team. An undated call returns
project-lifetime figures, so always pass the range: `totals` and the per-user `consumption` rows
(`userId`, `total`) follow `start_date` and `end_date`, and a member ranking comes from those rows.
The per-day series (`include: ["usages.daily"]` per usage type, `["modelUsages.daily"]` per model)
carry no user dimension; `nsfwUsages` adds moderation totals and `activity` the raw event log. Never
attribute spend by adding up your own calls. Read consumption before setting caps: both are in CU
over the billing period, and a cap below what a member has already spent stops them at once.

## Worked example: lock a project to approved models and cap the contractors

1. `scenario_tools_search` with `query="model access"`, then `query="team members"`: schemas and
   lanes for the calls below.
2. `scenario_tool_execute_read` with `name: "model_access_get"`,
   `parameters: {"team_id", "project_id"}`. The team is in blocklist mode, so "only these three
   models" is not expressible: tell the user to switch the team to allowlist in the web app's team
   settings, then re-read; unattended, log the gap with the calls below and stop, blocking any
   models the task names as unwanted at project level in the meantime.
3. In allowlist mode, the team list first: `scenario_tool_execute_write` with
   `name: "model_access_update"`,
   `parameters: {"team_id", "project_id", "level": "team", "add_models": [<the three ids>]}`; this
   is the call that needs the caller to be a team admin over OAuth (`context.userRole` on the
   `teams_list` row says whether they are). Then the project: `level: "project"`,
   `projects: [<project id>]`, the same `add_models`, which succeeds only because the team list now
   carries them.
4. `scenario_tool_execute_read` with `name: "team_members_list"`: the two contractors' member ids.
   `scenario_tool_execute_write` with `name: "team_members_update"`,
   `parameters: {"team_id", "project_id", "member_ids": [<two ids>], "max_consumption": 2000}`. On
   `status: "partial"`, call again with `remaining`.
5. `scenario_tool_execute_read` with `name: "api_keys_list"` for the project. A render-farm key
   running as `admin` is narrowed with `api_key_update`, `role: "assets.read;models.run"`, and any
   key nobody can account for is deleted only after the user confirms it by name.
6. Confirm: `model_access_get` with `project_id` shows the project list `configured` with the three
   ids; later in the period, `usage` with the date range and `include: ["usages.daily"]` shows the
   contractors' consumption against the cap.

## Common mistakes

- Editing model access without reading `models_management`: `add_models` blocks in one mode and
  allows in the other.
- Trying to lock a team to a short list while in blocklist mode: that is an allowlist job, and the
  mode switch is a web-app setting.
- Team-level writes through an API key: refused by design; the caller is a human team admin over
  OAuth.
- `arguments` instead of `parameters` on the executor: dropped silently and surfaced as a scope
  error (see `scenario`).
- Setting caps with a `team.members.manage` key: it can change roles, not caps.
- Reading an undated `usage` call as the period's spend: its figures are project-lifetime. Pass
  `start_date` and `end_date`, rank members from the dated `consumption` rows, and use the per-day
  series only to cross-check a period total, since it carries no user dimension.
- Expecting `api_keys_list` to show team-scoped keys: they exist only in the portal.
- Passing `project_id` to `team_members_add` to grant project access: `project_ids` grants;
  `project_id` is tenant context.
- Deleting a key or removing a member without listing and confirming first: the delete lane is
  irreversible, and `api_key_delete` refuses the session's own key.