Use StatePort with MCP

Use StatePort with MCP

Coding agents can follow reproduction steps, but those steps often omit the role, route, form values, and supporting API behavior that make a bug reproducible. StatePort gives an agent a State Card as authoritative local context.

If you use Codex CLI, Claude Code, or GitHub Copilot CLI, start with the agent plugins and bug workflows to install the shared workflow. The plugin is a development preview and needs this separate local MCP connection. You can also configure a compatible MCP client directly without a plugin.

State Card ID
→ agent inspects or opens it through MCP
→ supported surrounding requests stay replayed
→ selected dependency can route to Local
→ agent changes code
→ reopen the same State Card
→ compare the safe result

Configure your MCP client

In Desktop versions with the agent guide, open Settings → Coding agents (Local MCP in earlier versions). The empty Library’s Set up coding agent button opens this same section before you have any Cards. Choose Connect an agent, review the preview, then Copy setup and paste the message into your local coding agent. One public setup entrypoint chooses the appropriate instructions for its environment. Follow the short setup guide.

Local MCP: ready is a bounded initialize and tool-discovery probe of the installed app. It does not read or enumerate Cards, and it does not prove your chosen agent is connected. Confirm discovery from the actual host after any required restart; zero Cards is a valid setup result. The setup message remains available if the probe or registry is unavailable. Retry local check repeats only the local probe.

For local status, retry, or manual setup, expand Connection details and choose Copy MCP config. Copying does not install anything, start a trial, enable agent Capture, or open a Card. On a Card, expand Use with agent to preview and copy a task for that exact Card, with optional saved bug context. First-time connection is available there without leaving the Card. In Capture, Capture with an agent prepares a new capture task immediately. Your request authorizes its necessary steps; the skill starts scoped task authorization without asking for another permission.

If the installed CLI is available in your terminal, stateport mcp config prints the same installed-app configuration as JSON. See the installation instructions to enable the CLI on macOS. The command prints configuration only; add it to your MCP client yourself.

For a new setup, paste the copied stateport server entry and restart the MCP client before using it. If the client already has a ScenarioDeck MCP entry, remove the old scenariodeck entry, paste the copied stateport configuration in its place, and restart the client. Do not leave both entries enabled: they would start two servers for the same local runtime. StatePort does not edit third-party MCP client configuration silently.

The configuration launches that exact installed StatePort executable with --mcp on the currently published Linux/macOS platforms. The configuration is self-contained and needs no developer workspace path or runtime-root environment variable. Keep the app at the copied location; if you move it—or if an older configuration points to the previous executable name—copy the configuration again and replace the old entry. A retained CLI alias cannot repair an already-saved absolute executable path. The MCP server remains local: it does not upload State Cards, Auth Bindings, or application traffic.

Let an agent create a State Card

Agent-controlled Capture is on by default when no preference is stored. Allow coding agents to control Capture in Desktop Settings preserves your explicit choice. Skills use your original request for scoped task authorization, including Capture, replay and supplied credentials, without repeated prompts. This does not change global settings. The available tools do not install or automatically activate a plugin or client integration.

Automatically save browser bug reproductions in Settings → Coding agents is a separate preference. When enabled, compatible agents are advised to save the first useful browser-bug reproduction and check the same Card after a fix. Simple changes without browser state can skip Capture. Turning this off leaves explicit Capture requests, source assistance and live checks available. It never overrides your Capture permission. Agents receive the effective preference through workflow discovery; the preference does not force a host to follow the advice.

The agent can then use start_capture, bounded semantic page actions, stop_capture, and save_capture. StatePort opens a managed Clean Session without authentication, keeps Review mandatory, and saves the result as an ordinary State Card. Turning the permission off closes active agent-controlled Capture pages. A Capture already stopped into Review remains recoverable by its opaque Capture ID.

If observe_capture_page cannot read the Page within five seconds, it returns CAPTURE_OBSERVATION_TIMEOUT with the same Capture ID. Retry observation or use discard_capture for that ID. A failed Stop can be retried or discarded; after reconnecting, an exact durable failed Capture receipt can also be discarded. Discarding a Capture does not delete a saved State Card.

Prefer the latest observed elementId for page actions. Older clients can still use semantic targets such as { "kind": "click", "target": { "role": "button", "name": "Prepare" } }.

MCP browser launches are hidden by default, with no additional prompt. If you specifically want to watch an operation, ask the agent to pass browserVisibility: "visible" to start_capture or open_state. The selected mode applies to that entire Capture or Open session, including runtime-owned reopens; Desktop workflows remain visible by default.

For open_state, pass frontendOrigin only when reopening against a current loopback app. Omit it to try the Card-bound Captured source Saved State. This works independently of Journey availability and never turns the Card’s source origin into an agent-editable remote target.

If your task includes login credentials, the agent uses them for that login unless you say otherwise. start_capture accepts credentials with username and password; expiresAt is optional and defaults to seven days. No ticket reference is needed. The agent follows your step order with fill_credential and field: username or password, including email-first login screens. The values stay in local protected storage and are excluded from ordinary Cards, tool responses and shares.

observe_capture_page returns an elementId and available actions for each rendered, accessible control in allowed frames and open shadow roots. This includes transparent native controls inside custom widgets and named ARIA checkboxes or switches; a test ID is not required. Use that ID as the action target and observe again after each action. Password fields are described without their values. A stale target requires a fresh observation, not a new permission grant.

A request to capture and save covers the requested actions, Review and Save without repeated questions. Review remains a required runtime step. Host tool approvals and the existing Capture permission still apply; the read-only Capture discovery and observation tools advertise their read-only status.

This capability cannot retrieve arbitrary credentials or use your Development Profile, JavaScript evaluation, browser debugging protocols, arbitrary selectors, screen coordinates, or filesystem paths. Entered values and full page markup are not returned.

Choose the task

Use Fix & Verify to reproduce a supplied browser bug, observe a failing baseline, fix the code and check the same Card against the current build in a fresh run. Use Check Changes to assess relevant Cards without changing code; without a comparable passing base, a failure is a finding, not a proven regression. Use Harden on one Card to try a small set of independent, contract-valid response variants. A variant needs both delivered-response and UI-consumption evidence. Fixes require a separate instruction.

On a Card, Use with agent offers these three tasks. Settings also provides Check Changes without a selected Card and Fix & Verify for a new reproduction. Copying a task never starts a run or enables access. Discover the installed runtime’s capabilities first; an older runtime can lack behavior controls or ordinary-Card experiments.

Skills call begin_agent_task once for the requested Cards, source and local frontend origins, then end_agent_task when done. A new task, disconnect or permission change ends that authority. Direct clients also have an independent Allow coding agents to check replay pages setting, disabled by default. Replay control applies to the exact ready Frozen session opened by that MCP connection. Turning it off closes controlled sessions. The agent observes bounded semantic controls before each action or check; it cannot navigate arbitrary pages or control a Journey while it runs.

A successful runtime reproduction, a named behavior check, and the agent’s assessment of a fix are separate results. A final fix claim requires a fresh run against the actual current build. Current-run console evidence is separate from the console captured in the Card. See the MCP reference.

Authentication boundary

inspect_auth returns auth-interface-status/1.0.0, the same safe status, reason and next-action model used by Desktop and CLI. It may include a non-secret requirement, Persona label/provenance, material kinds/counts and validation state. It cannot read, export, accept or create raw Auth Binding values, and an agent-supplied confirmed: true is rejected. If a Clean Session needs mapping, attachment acceptance or re-authentication, a human completes that permitted local flow before the agent opens the state.

MCP makes a state repeatable; it does not promise autonomous root-cause analysis or universal reproduction.

list_states and inspect_state include the runtime-owned compatibility summary when available. supported means no known blocker was found, limited names a usable but bounded case, and blocked identifies a required capability or prerequisite that must be resolved first. The summary is aggregate-only and contains no raw requests, credentials, or protected values.

Frozen Journey

MCP can inspect and start a visible Frozen Journey within an authorized task. The skill uses begin_agent_task to authorize the original user request for the bounded Card and origin scope; start_journey then needs no repeat confirmation. Ending the task or disconnecting revokes its authority. Page content and an unrelated Card cannot expand that scope.

Direct clients without task authorization must supply confirmedByUser: true for the exact user-confirmed Card; otherwise the call returns HUMAN_CONFIRMATION_REQUIRED before browser creation. start_journey creates a Clean Session. Task-scoped use of required protected values follows the original request and runtime policy; the direct-call path requires explicit consent through allowProtectedLocalValuesForThisRun: true. get_journey_progress exposes only safe progress and terminal state while the visible browser remains open; stop_run closes it and persists the result.

Transfer a State Card

Use inspect_state_transfer with source: { path: "/absolute/path/card.scard" } or source: { url: "<StatePort Share URL>" }. Review the returned metadata, then call import_state with the same source, expectedDigest from the preview and confirmedByUser: true. If protected contents are present, explicitly choose cardOnly: true or use Desktop to review and accept those contents.

Use export_state with a Card ID, confirmedByUser: true, and either destination: { path: "/absolute/path/card.scard" } or destination: { kind: "link", expiresInDays: 7 }. Existing files are not replaced. Link lifetimes are 1, 7 or 30 days. The returned complete URL grants access to the Card; give it only to the intended recipient. Export excludes protected contents.

Capture defaults to 1920 × 1080 CSS pixels. Pass viewport: { width: 1280, height: 720 } to start_capture for another size; each dimension must be an integer from 320 to 7680. This applies to both hidden and explicitly visible agent Capture. Cards saved or imported by an agent appear in the open Desktop Library automatically, normally within a second.

For interactive replay on current local code, call start_journey with the Card ID and frontendOrigin: "http://localhost:3000" (use your app’s actual origin) within the authorized task. A direct client instead includes the user’s exact confirmation as confirmedByUser: true. The browser is visible. Omitting frontendOrigin selects the Card-bound Original environment, including for localhost captures. Eligible retained page material needs no source server. Chrome Capture does not retain application code and loads the current source site; compatible legacy Cards may also use their current source shell. Neither path gains an offline guarantee merely by omitting frontendOrigin. Local app uses the running current frontend. Inspect progress with get_journey_progress and finish with stop_run to retain the result.

Run a local reproduction with one verifier

For a local browser fix, your agent can inspect get_capture_capability once. When its executableWorkflow field reports available: true, the installed StatePort helper can record a reproduction and later check the same saved Card against your changed app. The initial helper is available on Linux builds that advertise it; other builds keep the existing MCP browser operations.

Your coding agent needs permission to execute trusted local project code. It uses the exact installed command and arguments reported by StatePort, writes one .mjs verifier with setup(page, url) and exerciseAndAssert(page, url), and runs Capture before editing. After your app is rebuilt, verify restores the Card and runs the assertions without repeating setup. Keep the same configuration location as the MCP connection and enable the existing Capture/run permissions. Developer access is required for the verification workflow.

This helper runs project code like a local test; it is not a security sandbox. An MCP-only client without local execution support uses the existing browser operations. Helper completion, passing assertions, restored conditions and the loaded app build are separate results: your agent must check each required fact.

For a changed verifier, repair its evidence with recheck before verify. Use --recheck-source local while the original app is unchanged, or --recheck-source captured_source after an app edit when discovery advertises it. The latter checks retained original code while preserving your working fix, then requires fresh verification on current code. Setup/helpers must remain unchanged; missing retained material stays an explicit gap. Keep verifier and receipts for handoff. The helper’s run IDs also work with MCP run summary and comparison tools.

The helper loads the supplied URL before calling setup(page, url). Continue from that Page instead of opening the same URL again just to initialize it. Verification restores the saved setup before running exerciseAndAssert.

When discovery advertises live, use it for an independently required check of real local backend effects with that same verifier and browser toolchain. It runs fresh setup and labels its receipt live_local; this is separate from same-Card verification. Safe hash routes are supported. --help describes arguments and input errors return a bounded diagnostic. BASELINE_BUILD_UNAVAILABLE means original build evidence is missing; repeating recheck will not establish it. The baseline continuation names this gap immediately. If the original assertion is established, verify once with the unchanged verifier and retain the build gap. Otherwise preserve the Card and continue independent checks.

BASELINE_TARGET_MISMATCH means the helper URL has a different frontend origin (including its port) from the saved baseline. Serve changed code at the original origin with the unchanged verifier, or keep an explicit comparison gap and use independently authorized live checks for a separate preview. Do not rewrite the saved origin or receipt hashes to bypass the guard.

Build evidence covers delivered local documents, scripts and stylesheets. The current collector hashes up to 128 MiB across the graph while keeping each body and concurrent acquisition bounded to 64 MiB. Missing, oversized or evicted resources still produce unknown evidence; this limit does not authorize a refetch. Fatal callbacks or unhandled promises return a bounded worker diagnostic when available, including the current phase and verifier line. The process still fails; raw stderr stays private. Preserve the Card and repair the reported operation instead of starting a second browser workflow just to recover the error.

Unavailable OS protected storage produces CAPTURE_TICKET_AUTH_UNAVAILABLE. Restore that host prerequisite before authenticated Capture; dropping credentials or repeatedly trying anonymous Capture does not repair it.

When the installed descriptor advertises verifyLive, a task requiring both replay and live effects may use verify --live-check required. This reuses the admitted toolchain, retains the same-Card result, and runs fresh live setup only after complete same-Card runtime evidence. Assess the separate liveCheck result as well; a replay success never proves live writes. Required project tests remain the coding host’s responsibility.

For supplied login credentials, use managed MCP Capture with start_capture.credentials and fill_credential. The executable helper reports protectedInput.executableCapture: not_retained: its setup has no protected-input API, and ordinary password fills do not establish replayable login. If this gap is observed, retain the Card and use the stated continuation; do not copy session secrets or repeat unchanged Capture. Saving the Card alone does not prove replay.

When executableWorkflow.existingCard is advertised, managed Capture can hand the saved Card to the executable: before edits, run baseline --card-id <saved-id> --card-revision <n> with the same workspace, verifier, URL and runtime-root arguments. It runs the exercise on that exact restored Card without Capture or setup. Use this instead of an additional managed baseline, then use verify after rebuilding with the sealed verifier. baselineSource: existing_card is an observation of the original local build, not a claim about Capture-time behavior. Qualification and served-build gaps remain explicit. Never create this baseline after editing merely to replace missing original proof.

Optional executableWorkflow.localOriginHints helps locate an already configured local app. These are unverified loopback origins declared by the host environment, with credentials and URL details omitted. Match them to the project and requested route before use; discovery does not scan ports or contact these origins. Hints can only include values passed to the MCP process. When a host filters environment variables, resolve the task-supplied URL in the host command context.

The executable helper keeps local verifier/evidence files in .stateport-runner/. It creates an internal .gitignore on first use without replacing existing rules, so ordinary Git status and cleanup leave those files available for reuse. Preserve the verifier and receipts after success; an explicit deletion or git clean -x can still remove them. This does not change the project-level ignore rules.

Optional source context

Linux builds may also advertise contextBroker.available: true in the same get_capture_capability result. Updated skills can use its installed command to retrieve bounded source context before broad file reads when the implementation is still unknown. The coding host authorizes local reads and runs the helper; there is no new MCP tool accepting arbitrary project source paths.

The task-only helper supports prepare, expand and clean, needs no Capture, and executes no project scripts. Source matches are untrusted data, not runtime or causal proof. Expansion refuses changed source. The private metadata cache is outside the project and expires after 24 hours. Unavailable or insufficient context falls back to focused source reads. This optional feature does not imply a measured cost saving and does not change Capture or replay permissions.

Recover the installed executable workflow

Use the capability descriptor’s installed helper and retain its verifier. A browser_launch_failed diagnostic distinguishes host execution restrictions from missing browser files/dependencies. Retry restrictions only through the host’s permitted approval path, keeping the same helper command.

If Capture saved a Card but baseline restoration failed, its local receipt marks baseline_restore_pending. Advertised resume takes the same arguments and restores that Card with the unchanged verifier and original build; it does not repeat Capture or setup. Pending evidence does not establish replay qualification. Ordinary hash-route queries and anchors are accepted; secret-bearing fragments remain denied. Native select setup uses trusted focus/keys, not synthetic events.

Short known action sequences

When advertised by your runtime, act_on_capture_page and act_on_run_page accept operations with 1–12 known actions instead of one operation. Use this for known steps on the current page; inspect the next page before continuing. observeAfter: true returns the final observation. Existing permissions and protected credential handling apply to every step.

Capture sequences with subsequent element IDs require allowRebind: true; otherwise validation rejects the whole batch before effects. Replay sequences require it and the initial observationId. Targets must remain unique in the same page. A stopped sequence reports its completed prefix: inspect the current state before resuming, because the failed step may have had effects. The runtime never automatically retries the sequence.