Scenario and MCP reference

Composal Verify runs saved project Scenarios against a managed preview or an HTTP(S) environment you operate. Each grouped Run saves a snapshot of the selected Scenario versions, personas, target, and runner. For a pull request, Verify selects relevant saved Scenarios, runs them against the exact PR commit in parallel within account and organization limits, and reports the results. Start with the Verify overview, then use this page for setup and reference.

Organization members can read their organization's Verify projects, runs, findings and retained evidence. Owners and administrators can change configuration, prepare plans, start or stop runs, and manage credentials. These permissions apply to the dashboard, CLI and MCP connector. Credential secrets are write-only; interactive sign-in sessions and scenario recordings are restricted to their administrator creator.

Connect your agent

Verify is the default workspace when you sign in. Your organization opens directly into Verify, even without a repository. Each project shows recent and active runs, Scenarios, Environments, Findings, Knowledge, and Credentials. The organization switcher and collapse control stay at the top.

Findings lists every scenario failure and every bug reported by Discovery or Deep Scan, highest priority first. Each finding links to the run that last saw it. If an explorer or a Deep Scan rerun reproduces a bug the project already tracks, Verify adds an occurrence to the existing finding.

Members who manage Verify can click Resolve on a finding or choose Ignore from its action menu. Both move it to the Closed tab. When you resolve a finding from the active list, its row stays visible for 8 seconds with Undo. Closed findings offer Reopen. Choose Defer for 1 Day, Defer for 1 Week, or Defer Until… for an acknowledged issue you want to revisit. The reason is optional. Deferred findings move to the Deferred tab and return to Active automatically when their deadline arrives. You can reopen them sooner or extend their deadline from the action menu. Verify remembers the issue and deferral deadline without learning that it is a false positive.

The Active, Deferred, and Closed tabs show their totals across all priorities. Search finding titles and summaries, then narrow the results with the Priority control (All, P0–P4). Counts reflect your search across all pages. Use Source to show findings from Deep Scan, Discovery, or Scenarios, then choose a specific Run. The picker lists the 100 most recent runs with findings. To select an older run or one without findings, open its Findings tab and choose View This Run in All Findings. Filters include earlier sightings of a finding, and the evidence link points to the selected run. Use Clear Filters to reset search, priority, source, and run while keeping the current tab. You can also use com verify findings update.

The project Overview loads discovery, totals, active runs, pull requests, and recent runs independently. Available sections appear while the others load, and a failed section offers its own retry. Live activity refreshes without reloading the whole overview.

Deep Scan history shows each run’s findings, recorded checks, status, and timing. Choose With Findings, narrow by status, or search run titles and goals. Filters apply across the full history and stay in the URL. A run with no recorded checks is not a clean bill of health; Partial and Cancelled runs may still have findings worth reviewing. Choose a finding count to open that run’s Findings view.

Completed Deep Scans open on Findings by default, including links with a selected tester. Use the Findings tab at the far right of the workspace toolbar or append /findings to the scan path to share that view. Explicit thread, grid, and orchestrator selections remain selected after refresh. During a live run, the toolbar shows the number of agents running with a spinner, including while you review findings; choose it to return to the threads. It shows every reported finding in priority order, including what happened, what was expected, and how to reproduce it. Choose View Evidence & Actions to open the finding and its recording in the center workspace, at the moment it was observed. Navigation and triage actions stay above the recording, with Finding, Observations, Diagnostics, and Evidence tabs underneath. The Finding tab holds the reproduction steps; the other tabs retain the tester’s observations, diagnostics, and evidence files. Choose Back to Findings to return to the findings list you came from, such as the project’s Findings page, or to the run’s findings when you opened the finding from a shared link. Copy Findings copies the full run's fix instructions, or use Send to to hand them to Codex, Claude, or Cursor. You can return to the threads at any time.

Run status and navigation load separately from findings, including when you refresh the page. Findings load from saved reports without downloading browser activity or replay history. Opening a finding loads that tester’s recording and evidence; thread activity loads when you open a thread view. Switching agents keeps the run header, thread list, filters, and list position in place while the center view updates. If a section fails to load, use Try Again to refresh it.

Finding recordings open in a narrower, centered viewer that fits the window height. Choose Enter Theatre Mode at the top right of the viewer to expand it to the full pane width, or Exit Theatre Mode to return to the fitted view. Resizing keeps the same recording and playback position.

Use com verify deep-scan findings <scan-id> --json to retrieve all findings for one Deep Scan without its workspace payloads. Add --prompt instead of --json to print the full agent handoff. This includes every reported finding regardless of its current triage status. The API is GET /api/v1/organizations/{organization_id}/verify/deep_scans/{id}/findings.

Copy Prompt copies the full fix instructions for pasting into your coding agent. Use Review Prompt to inspect and edit them first, including worktree or branch instructions. Use the agent picker to choose Claude CLI or Claude Desktop. Claude CLI opens a terminal session; Claude Desktop opens the Code composer. Both pre-fill the prompt for you to review before pressing Enter. Your choice is remembered for Send to and Fix in. CLI links include up to 5,000 prompt characters; Desktop links include up to 14,000. Use Copy Prompt for the full instructions when a prompt exceeds those limits.

A new occurrence reopens a resolved finding. Ignored findings stay ignored until you reopen them manually. Replaying an existing occurrence does not change its status.

Verify checks findings independently. A separate model reviews the failed checks, steps, and screenshots to decide whether they show a product defect. If it confirms a P0 or P1 Deep Scan finding, Verify also reruns it in a fresh browser. The finding is confirmed only if that rerun reproduces the bug.

During the check, the finding shows Checking. If the screenshots show the expected result, so the run misjudged a working page, the finding shows Not confirmed with the reason. If the check doubts the finding for any other reason, such as a page still loading or a sign-in problem, cannot decide or cannot run, or a rerun does not see the bug again, it shows Unverified. Both stay listed below confirmed findings, on the Findings page, the run page, and in pull request comments. Verify checks either kind again when the finding receives a new occurrence.

When every scenario in a pull request run that did not pass failed only on a Not confirmed finding from that run's own screenshots, the run reports Not confirmed instead of Failed. The GitHub check finishes as neutral, which does not block a merge. The GitLab commit status is skipped; whether that blocks a merge depends on your pipeline settings. The results comment still lists each failure and why the check ruled it out. A skipped or blocked scenario, or one unverified or confirmed failure, keeps the run failed.

Source is a separate workspace, currently enabled by a feature flag only for the Vex organization. Choose Source at the bottom of the Verify menu to browse source, Changes, Queue, Transcripts, and repositories. Use Back to Verify to return. The flag controls which workspace appears when you sign in; repository permissions and CLI/API access apply independently.

Open organization settings at /{organization-slug}/settings, team access at /{organization-slug}/settings/members, and billing at /{organization-slug}/settings/billing. Existing settings links using organization IDs redirect to these pages.

Organization billing shows CI minutes, CI artifact and cache storage, repository storage, and transcript storage charts, allowances, and add-ons only when Source is enabled for that organization. Browser verification usage remains visible without Source.

Use the hosted Composal Verify MCP connector from a web assistant or local coding agent. Hosted verification runs without a local CLI or browser installation. Add this Streamable HTTP server URL:

https://composal.ai/api/v1/mcp/verify

In Claude, open Settings → Connectors → Add Custom Connector, enter the URL, then connect. Sign in to Composal and choose the organization on the consent page. Check the displayed callback address before approving; a client supplies its own display name. Verify must be enabled for the selected organization. The connector gets verification access only, and every operation still checks your current organization role. Configuration and run mutations require administrator access where the dashboard requires it too.

For a local coding agent, add the same URL as a remote HTTP MCP server and use its OAuth connection flow:

# Claude Code, then run /mcp inside it to sign in
claude mcp add --transport http composal-verify https://composal.ai/api/v1/mcp/verify
# Codex
codex mcp add composal-verify --url https://composal.ai/api/v1/mcp/verify
codex mcp login composal-verify

Verify home shows the same commands for your workspace, with an install link for Cursor. Then ask the agent to set up Verify for the repository: it creates a project, adds the address remote browsers can open and starts an exploration through the projects_* tools. The existing com mcp local tools and personal-token HTTP endpoint remain available; do not paste access tokens or test-account passwords into chat or configuration files.

Start with a request like:

Help me define acceptance criteria for checkout. Read the product sources I provide, agree the important customer journeys with me, and run them remotely against my staging URL. Show me the live run and explain any failures.

The connector provides a verify_product prompt and verify_setup tool. They guide the model through your product and roles, distinguish current behavior from intended behavior, and help you agree on acceptance criteria in plain English before configuring the remote environment and scenarios. To give a web assistant access to your product's context, supply the relevant brief or files, or use a local coding agent with repository access. A remote browser cannot reach your laptop's localhost; use an accessible preview or an explicitly arranged tunnel.

The hosted MCP provides tools to configure project targets and YAML Scenarios, prepare and start grouped Runs, explore your app, read results and evidence, and request configured PR checks. Start with verify_setup to find the organizations, projects, environments, Scenarios, and accounts you can access. For retries, reuse the returned IDs and digests and the same idempotency_key values.

Full resource administration is available through the CLI's com verify admin <resource> <action> commands, including project credentials, personas, private-network connections, immutable environment revisions, knowledge and memory, and grouped Run inspection. Run com verify admin --help to list resources and com verify admin <resource> help for actions and identifier flags. Supply private request objects through --body-file or --body-stdin; keep secret values out of chat and command arguments. Evidence downloads use com verify admin evidence download --id <evidence-id> --org <org> --output-file <path>. The hosted MCP returns evidence metadata and dashboard links.

Agree on the actions the agent may take and its budget before launching. It should return the live-run link, check progress until the run and cleanup finish, and report passed, failed, blocked, and inconclusive results separately. It must not weaken acceptance criteria to obtain a pass. Saved organization memories help with navigation and workarounds; assertions determine whether the app meets the criteria.

OAuth uses authorization codes with S256 PKCE, one-hour access tokens and rotating 30-day refresh tokens. Tokens are bound to this MCP resource and one consented organization. Removing organization membership invalidates access. Clients can revoke through the advertised revocation endpoint; disconnect using a client that performs OAuth revocation. Client registration supports public web clients and native loopback callbacks; Client ID Metadata Documents and confidential-client authentication are not supported in this first release.

The HTTP transport supports the stateless 2026-07-28 MCP revision, plus the 2025-11-25, 2025-06-18, and older initialization handshakes for compatibility. It returns JSON responses. For long runs, use the saved project Run ID to check progress through tools. The chat request does not need to stay open. Your Claude account, plan, and workspace policies may control whether you can add custom connectors.

Monitor finished runs in ChatGPT

With the Composal plugin connected, ask a ChatGPT Work chat to monitor a verification run or QA exploration and explain its results when it finishes. For example:

Watch this verification run. When it finishes, summarise the outcome and inspect any failed scenarios.

Composal provides verify.run.finished and verify.exploration.finished events. You can monitor all future runs in an organization or one run by its public ID. Events include failed, blocked, timed-out, skipped, cancelled, and partial outcomes where applicable; they are not limited to successful runs.

Monitoring uses the connected account's Verify access and stops if that access is revoked. Delivery is swept every minute; slow callbacks can delay a busy batch. Subscriptions expire after one day by default and ChatGPT can refresh them. Finished delivery receipts are kept for seven days, and cleanup preserves pending work. Events missed while monitoring is stopped or expired are not replayed; use the run read tools to check the latest results. An exploration's final narrative report may still be writing when its team finishes.

Events require MCP protocol 2026-07-28. ChatGPT supports them in Work chats on web, desktop Work with Cloud selected, and dots. Rescan the Composal plugin after its MCP server gains event support, then ask ChatGPT to start monitoring. To stop, ask ChatGPT to stop monitoring the run.

Run project scenarios

A project owns its saved YAML Scenarios, Personas, Credentials and Environments. Website icons appear automatically after the project is saved; an unavailable website does not prevent setup. Each run saves a snapshot of the selected definitions and creates one ScenarioRun per scenario. Independent scenarios execute in parallel within organization limits. Shared account and TOTP locks queue conflicting journeys; adding concurrency does not create accounts.

com verify scenarios download --org acme --project storefront --dir scenarios
com verify scenarios lint scenarios
com verify scenarios upload --dir scenarios --dry-run --json
com verify scenarios upload --dir scenarios --json
com verify scenarios run scenarios/home.yaml scenarios/profile.yaml --org acme --project storefront --environment Preview --wait --json
com verify runs list --org acme --project storefront --json
com verify runs get <run-id> --org acme --project storefront --json

Download includes project.yaml for upload context. Upload validates all files and saves them atomically; lint checks the bundled schema offline. Run executes the files as written without saving them. When a file's id, version, Persona, and run definition match an active scenario in the selected project, its result appears in that scenario's history. New, edited, stale, or unmatched files keep separate run history. Upload edits first to include their runs in the saved scenario's history. The dashboard can run selected saved scenarios.

Schedule daily runs

Open a project's Scenarios page and select Schedule Run. Choose an environment, All scenarios or By label, the daily time and time zone, and saved credentials for personas that sign in. New scenarios matching that selection are included automatically.

Notifications defaults to Email, sent to the account that saves the schedule. No integration is needed. To send reports to Slack instead, choose Slack and a connected channel. Connect Slack in Integrations and use /composal subscribe all in a channel to make it available. Scheduling requires an organization owner or administrator.

Each scheduled run uses the latest saved scenario definitions and the selected credentials on that environment. Daily timing follows the selected time zone, including daylight saving changes. Your chosen destination receives every completed outcome with a link to the full report, even if its general subscription only reports failures.

Use Pause, Resume, or Edit on the Scenarios or environment page. Its schedule history links to recent reports and shows launches that were blocked or skipped. Resuming starts with the next daily time. If a previous scheduled run is still active, the next occurrence is skipped. After a scheduler interruption, one missed occurrence is caught up. An unavailable credential blocks the launch; removing the schedule owner's administrator access pauses future launches. Signup scenarios need a fresh email-link inbox for each run.

YAML version 1 uses one Persona and prose steps/outcomes. Version 2 declares named actors, their Personas, and evidence ownership. Every actor must be available in the same project. A requirement for a distinct teammate needs a distinct working account.

For a PR, enable the project's PR Testing settings and choose its repository, environment template and preview source. Verify reads the current source diff, selects relevant saved scenarios with recorded reasons, prepares one grouped run on an exact-commit preview, and publishes its results. Low-confidence scenarios remain explicitly untested. A missing match is not a passing browser result. Manual selection can run other saved scenarios from the PR page.

com verify pull-requests run 45 --org acme --repo storefront --head-sha <commit-sha> --idempotency-key <stable-key> --json
com verify pull-requests get <request-id> --org acme --json

The PR report links the grouped run and records each scenario's result and findings. On the run page, a failed, blocked or timed-out scenario shows Fix in under its summary, which hands that scenario to Codex, Claude or Cursor with the com command for reading the run's full results. Cleanup is reported separately: cleanup trouble does not change a passed product verdict into a failed product verdict. Failed assertions, missing prerequisites and untested requirements remain visible. Retrying an uncertain request uses the same idempotency key; deliberately rerunning uses a new key.

Author project YAML Scenarios

Author optional application cleanup in the dashboard's Cleanup (optional) field or as a cleanup: list in YAML. The runner attempts those instructions after checks pass or fail, while time and access remain, and reports cleanup separately. Omitted or empty cleanup on a new Scenario requests no application work. Updates that omit the field preserve saved instructions; cleanup: [] clears them. Browser shutdown and recording finalization remain automatic. Keep deletion that you are testing in steps; use cleanup only for work after the checks.

Cancelling a browser run stops further testing immediately. If the browser is still reachable, Verify briefly attempts to save its recording, screenshots, logs and partial report. Evidence can appear shortly after cancellation; an unavailable browser or an interrupted upload does not delay cancellation.

Use the Scenario file guide for the schema, writing instructions, named actors, and versioned uploads. A Scenario states starting conditions, the steps the model must complete and observable expected outcomes. Keep credentials in the project's Credentials. PR selection chooses from these saved definitions; it cannot generate replacement requirements from a source diff.

Discover initial requirements

Discovery maps an application's flows and reports observations. Review the intended requirements before saving an observed check as a project Scenario. Run that Scenario on a suitable environment to establish acceptance.

Browser Discovery continues within its time budget without a fixed number of tool calls or a report-argument size cap. As model context grows, Verify compacts older history using Roder's compactor, preferring provider-native compaction. The current observation, saved report, evidence references, instructions and cleanup state are retained so work can continue without replaying completed actions. A partial run can still reflect unfinished coverage, access blockers, or the time limit; review each agent's stopping reason.

Open Composal chat on the discovery activity page to review the run instructions and assigned task charters. The agent reads the current page through its page tools and can open run instructions, findings, or an assigned task for you. These tools do not change an already launched run. If a large plan exceeds the context limit, the agent reports which content it could not read.

The discovery page shows two lists. Findings fills with reported problems as the run progresses, most severe first. Open a finding to see the expected outcome, what happened, the steps, and the recording. Use Send to Agent to send it to Codex, Claude, or Cursor; the button under the list sends all findings at once.

During the run, the second list shows Agents. It groups each orchestrator with its workers and shows their status, checks, and current activity. Select an agent to see its full activity. When the run finishes, New Scenarios replaces this list with the Scenarios the discovery saved. Open one to read its steps and expected outcome, or select View All Scenarios to see the project's remaining Scenarios.

Switch to Orchestrator Thread to follow reasoning summaries and tool activity as live updates arrive. Tool groups start expanded; each call shows its browser action type when available and whether it is running, completed, or failed. Expand a call for its recorded metadata. New workers capture scrubbed tool arguments and results; expand a call to read them. Credentials, typed values, mail bodies and browser images are omitted or redacted. Long payloads are truncated. Older workers did not capture payloads, so those calls show an unavailable message; updating a worker does not recover earlier calls. Scrolling up pauses following new activity; use Scroll to end to return to the latest entry. The message composer stays below the transcript. Polling restores missed activity after a connection interruption.

Keep data and scope safe

Name the permitted test data, actions and cleanup in the scenario. Match starting conditions to the selected environment and Personas. Production and fresh-account requirements are different prerequisites. A missing teammate or signup inbox remains a blocker. Browser recovery keeps the original requirements and authority boundaries.