CLI & MCP Tools

Usertopia provides command-line and AI-agent tools for power users. Use the CLI (Rust-based) for managing projects, stories, and test runs from your terminal. Use the MCP Server (TypeScript) for AI agent automation with tools like Claude Code.

CLI

Rust-based command-line tool. Fast, scriptable, CI/CD-friendly.

MCP Server

TypeScript Model Context Protocol server. 41+ tools for AI agent automation.

CLI Installation

Build the CLI from source. You will need Rust installed on your system.

# Clone the repository
git clone https://github.com/rocketpowerllc/usertopia.git

# Build the CLI
cd usertopia/cli
cargo build --release

# The binary is at target/release/usertopia-cli

CLI Authentication

Set your API token and endpoint as environment variables. You can find your JWT token in your Usertopia account settings.

# Set your API token (from your Usertopia account settings)
export USERTOPIA_TOKEN="your-jwt-token"
export USERTOPIA_API_URL="https://your-api-url.amazonaws.com"

Tip: Add these to your shell profile (~/.bashrc or ~/.zshrc) so they persist across sessions. Never commit tokens to version control.

CLI Commands

The CLI provides commands for all major Usertopia operations.

Command	Description
`projects list`	List all projects
`projects create --name "My App"`	Create a new project
`stories list --project-id <id>`	List stories for a project
`stories create`	Create a new story
`test-runs create --project-id <id> --base-url <url>`	Start a test run
`test-runs status --run-id <id>`	Check test run status
`bugs list --project-id <id>`	List bugs for a project
`bugs create`	Report a new bug
`dashboard stats`	View dashboard statistics
`swagger import --project-id <id> --file spec.yaml`	Import Swagger/OpenAPI spec

MCP Server Setup

The MCP (Model Context Protocol) server lets AI agents like Claude Code interact with Usertopia programmatically. Install and configure it as follows:

1. Build the MCP server

# Install dependencies
cd usertopia/mcp
npm install
npm run build

2. Add to your Claude Code configuration

Add the following to your ~/.claude.json file:

{
  "mcpServers": {
    "usertopia": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/usertopia/mcp/dist/index.js"],
      "env": {
        "USERTOPIA_TOKEN": "your-jwt-token",
        "USERTOPIA_API_URL": "https://your-api-url.amazonaws.com"
      }
    }
  }
}

MCP Tools Available

The MCP server exposes 41+ tools organized by category. Each tool maps to a Usertopia API operation and can be invoked by AI agents.

Projects

List, get, create, update, and delete projects.

Stories

List, get, create, update, delete stories, plus AI-powered story generation from recordings or Swagger specs.

Tasks

List, get, create, update, delete, reorder tasks, and validate task execution within stories.

Test Runs

Create, list, get, check progress, view results, generate reports, and cancel test runs.

Bugs

List, get, create, update status, assign, add comments, view stats, and close bugs.

Jobs

Create, list, get, and cancel batch compute jobs (analyzer, tester, fixer).

Swagger

Parse, upload, and retrieve Swagger/OpenAPI specifications for API test generation.

Recordings

List, get, request upload URLs, and reprocess session recordings.

Dashboard

View aggregate stats, recent playbacks, test run summaries, and activity feeds.

Cycles

Run a complete test cycle end-to-end: create a test run, poll for progress, and retrieve results.

Using MCP with Claude Code

Once the MCP server is configured, you can ask Claude Code to interact with Usertopia using natural language. Here are some examples:

# Once configured, you can ask Claude Code to:
"List all my Usertopia projects"
"Create a test run for project proj_123 against https://myapp.com"
"Show me the bugs for my checkout project"
"Generate user stories from the Swagger spec"

Claude Code will automatically discover the available MCP tools and call the appropriate Usertopia APIs on your behalf. No manual API calls or scripting required.

Automation Examples

The CLI and MCP tools are designed for automation. Here are three practical use cases.

1. CI/CD Integration

Use the CLI in GitHub Actions to run Usertopia tests on every pull request. If tests fail, bugs are automatically filed.

# .github/workflows/usertopia-tests.yml
name: Usertopia QA
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Usertopia Tests
        env:
          USERTOPIA_TOKEN: ${{ secrets.USERTOPIA_TOKEN }}
          USERTOPIA_API_URL: ${{ secrets.USERTOPIA_API_URL }}
        run: |
          usertopia-cli test-runs create \
            --project-id ${{ vars.PROJECT_ID }} \
            --base-url https://staging.myapp.com \
            --wait

      - name: Check Results
        run: |
          usertopia-cli test-runs status \
            --run-id $RUN_ID \
            --format json

2. AI Agent Workflows

Use MCP tools to let Claude Code manage your entire testing pipeline. The AI agent can create projects, import Swagger specs, generate stories, run tests, and triage bugs -- all through conversation.

Example prompt: "Import the Swagger spec from api-spec.yaml, generate user stories for all endpoints, then run a full test cycle against the staging URL and summarize the results."

3. Bulk Operations

Use CLI scripts to batch-create stories or run tests across multiple projects. The CLI supports JSON output for easy parsing in scripts.

#!/bin/bash
# Run tests across all projects
for project_id in $(usertopia-cli projects list --format ids); do
  echo "Testing project: $project_id"
  usertopia-cli test-runs create \
    --project-id "$project_id" \
    --base-url "https://staging.myapp.com" \
    --wait --timeout 300
done

echo "All test runs complete."
usertopia-cli dashboard stats

Chrome Extension Last page

Documentation