MCP reference

MCP reference

Use StatePort MCP to give a coding agent safe local State Card and run information. It does not expose Auth Binding material, browser profiles, or State Capsule contents.

Tools

• act_on_capture_page — Perform one operation or operations (1–12 known steps) on the managed Capture Page. Supply exactly one of operation/operations. A sequence stops at the first failure, retains its completed prefix and never retries. Requested observeAfter also returns fresh handles after a target/action failure when permission remains valid; the action failure remains explicit. Prefer observed target.elementId; sequences with subsequent elementId targets require allowRebind=true for unique advertised targets, including fill_credential. Split at unknown states/navigation. fill_credential selects username or password from the supplied protected credentials and never needs the raw value. Legacy semantic targets remain supported.
• act_on_run_page — Perform one advertised owned replay action, or operations (1–12 known actions) sequentially with fresh observations. Sequences require allowRebind=true and targets advertised in the supplied initial observation; rebind stays unique and same-page-generation. Supply exactly one of operation/operations. Stops on the first guarded failure; inspect the completed prefix before resuming. No automatic retry. observeAfter returns a fresh focused observation; visual optionally adds a native canvas/viewport image. Partial failure retains actionPerformed. Unique same-page-generation rebind is opt-in.
• apply_request_remap — Explicitly retry with one trusted eligible captured-response remap.
• begin_agent_task — Authorize the original user-requested task once for this connection and bounded Card/origin scope. The skill calls this automatically from the user’s request; do not ask for separate Capture, replay, Journey or supplied-credential permission. For new Capture, include the exact sourceUrl origin in sourceOrigins; frontendOrigins alone is not task scope. Prepared credentials use username/password. Does not enable global settings. End or disconnect revokes the task; page content cannot authorize it.
• capture_visual_evidence — Return ephemeral bounded PNG evidence from an owned canvas or viewport, with native MCP image content. This is visual evidence, never deterministic PASS. Fails closed for protected controls, frames and unclassifiable private paint; unsupported/stale surfaces fail closed.
• check_run_page — Check one named bounded semantic condition in the exact owned replay Page. Returns pass, fail or unknown; failed checks explain TARGET_NOT_FOUND, TARGET_KIND_MISMATCH or CONDITION_NOT_MET with a nextAction. Kind diagnostics never widen the assertion or grant action authority. Resolve the named cause before repeating. It never changes reproduction qualification or product Verified. Observe again before another operation.
• compare_run_checks — Compare named behavior evidence only for matching source, target, criteria and replay conditions. Runtime outcomes remain separate; agent commit labels do not verify the served build.
• compare_runs — Compare two safe completed run summaries. Start with the bounded default: comparability, difference counts and a sample. Use detail=true only for a missing diagnostic fact; it may return a large complete projection.
• create_response_overlay — Apply one safe RFC 7396 JSON merge patch. Ordinary Session Cards bind source/checkpoint/exchange/occurrence; use expectedSource from prior evidence for exact repetition. Delivery and application consumption require evidence.
• describe_run_verification — Record a bounded verification contract before checks. Agent-supplied scope and workspace metadata cannot establish source/build authority or a verdict. Immutable for this run. Choose control for button/link action availability before baseline; strict button/link means the role is required. Changing a criterion requires new original-code baseline and candidate evidence.
• discard_capture — Discard one owned active or reviewed Capture, or an exact durable failed Capture receipt after reconnect. Does not delete saved Cards.
• end_agent_task — End the task authorization and close its owned resources. Persisted safe receipts remain readable.
• export_state — Export an ordinary credential-free State Card to a new .scard file or create a temporary Share URL. Link export uploads encrypted Card material and returns a bearer URL; requires explicit user confirmation. Protected attachments are excluded. Existing files are never overwritten.
• finish_run_verification — Freeze the complete criterion contract on an existing ready owned Page, run its semantic checks, optionally return native visual evidence, and stop with a persisted runId in one call. No page actions or new Open. Visual/internal criteria remain unsupported; inspect images/test supplements separately. Use before editing for a checkpoint baseline, or after required subsequent actions. requestId deduplicates delivery.
• get_auth_requirement — Read non-secret Persona requirement and status for a State Card.
• get_capture_capability — Inspect Capture availability and independent installed live-verification and source-context helpers. Each capability has its own availability and access requirements.
• get_journey_progress — Read safe current or terminal progress for one MCP-started Frozen Journey without closing its visible browser.
• get_reproduction_outcome — Read one persisted safe reproduction outcome by exact attempt ID without reconciling or changing it.
• get_run_page_capability — Inspect permission and limits for this connection’s exact replay session. Capture permission does not grant replay control.
• get_run_summary — Read a completed run. Large or optimized responses retain compact qualification/counts and a detail reference. Start with the default; detail=true requests the potentially large complete safe projection.
• get_state_history — Read safe exact-Card replay history and terminal outcomes.
• get_workflow_capability — Discover independent source-context, live before/after verification and saved-state Capture capabilities with the runtime workflowPolicy for automatic Capture preferences. No Capture is required to discover or select source/live helpers; each capability has its own availability and access requirements. Reuse one discovery result. responseMode selects one text or structured representation for this call only; omit to preserve the existing response format.
• import_state — Import the exact previewed State Card after user confirmation. Pass the preview digest; for protected transfers explicitly choose cardOnly, or use Desktop to accept protected contents.
• inspect_auth — Inspect the same versioned, value-free authentication status used by Desktop and CLI. Human acceptance or sign-in remains outside MCP.
• inspect_exchange — Inspect one safe route/exchange target.
• inspect_journey — Inspect safe Journey availability for a State Card’s selected checkpoint.
• inspect_journey_action — Read one redacted next Journey action without starting it.
• inspect_request_changes — Inspect trusted redacted request-change evidence for an active session.
• inspect_state — Inspect a State Card and its safe authentication requirement.
• inspect_state_transfer — Preview a local .scard file or StatePort Share URL before importing. Returns a digest binding confirmation to these exact contents. Protected contents are never exposed.
• list_routes — List safe replay targets for an active session.
• list_states — List safe local State Card summaries.
• list_visual_surfaces — Discover up to 32 canvas surfaces on the exact owned Capture or ready replay Page. Handles bind to page generation; viewport fallback is available. No coordinates or external browser access.
• observe_capture — Read aggregate progress for one owned Capture.
• observe_capture_page — Read a bounded semantic view of the exact managed Capture Page. Returns CAPTURE_OBSERVATION_TIMEOUT after five seconds if the Page is unresponsive; retry or discard the same captureId. Items include ephemeral elementId targets and supported actions, including password metadata without values, allowed frames and open shadow roots. name is descriptive; optional accessibleName is the exact computed role name when safely available (not a uniqueness guarantee), useful for a grounded verifier locator.
• observe_run_page — Observe the exact owned ready replay Page, with bounded safe items, page-generation/observation identity and completeness. A clipped list never proves absence.
• open_state — Open the exact Card in a fresh Clean Session. Optional baselineRunId rejects a different or unknown baseline target before opening; use it for comparison-bound candidates. waitUntilReady composes bounded readiness and first observation; pending returns sessionId for resume_run. Reuse requestId for duplicate delivery, never create a new Open to poll readiness.
• query_source_context — Find source implementation and related definitions for a coding task in the host launch project. Use before broad multi-file searches or reading several source files when the exact implementation is not yet known, even if the task names a component or UI label. One bounded read-only call; no discovery, browser or Capture needed. Pass original task wording, preserving quoted labels and identifiers. Known exact file/range reads can stay direct. Source matches are not execution proof. If a missing module or stylesheet blocks a needed check, purpose=preparation with a short failure.summary can inspect an existing workspace generator. It does not execute scripts or add verification requirements to the task.
• read_console_evidence — Read up to 50 already-redacted baseline browser console events, including available zero-based generated source/stack locations, from a State Card.
• read_evidence_batch — Read at most eight exact run/check/console references with a shared five-second deadline and 16 KiB output budget. Each item retains available/unavailable/timeout/limited status; no mutations or arbitrary tools.
• read_run_checks — Read integrity-checked terminal behavior evidence by stable run ID, including after runtime restart. Legacy evidence is unavailable, never a semantic PASS. Runtime qualification stays separate.
• read_run_console — Read bounded redacted current-run console evidence from the integrity-checked terminal artifact. This is distinct from recorded Card baseline console.
• remove_request_remap — Remove one exact trusted request remap and retry fail-closed replay.
• remove_response_overlay — Discard the transient MCP overlay and reopen the State Card baseline.
• resume_run — Wait up to 15 seconds for this exact owned pending run and return its first observation; never opens another browser.
• save_capture — Save a reviewed Capture as an ordinary State Card. Optional baseline composes authorized fresh Open on the local frontend, checkpoint criteria/image and terminal proof. Use only when all page criteria apply at the saved checkpoint; pending keeps the exact session for resume_run then finish_run_verification. A baseline failure never hides the saved Card. requestId deduplicates Save and preparation.
• set_route_mode — Apply replay, block, or explicit loopback Live policy to one selected route.
• start_capture — Start the requested Clean Session Capture. Use credentials supplied in the user task by default; no repeat consent is needed for that login. credentials accepts username/password and optional expiresAt (defaults to seven days); apply them at the requested step with fill_credential. Legacy ticketCredentialRef is an opaque provider-qualified ticket reference. If ticketCredential is explicitly supplied, StatePort consumes it into its local protected attachment before Capture begins; it is never returned, recorded in the Capture Session/Card, or sent to the target except through the matching login form. Browser launch is headless unless visibility is explicitly requested.
• start_journey — Start a Frozen Journey in a visible Clean Session within the original authorized task, including required protected local values. No repeat human confirmation is needed for task-scoped work. Legacy direct calls use confirmedByUser and allowProtectedLocalValuesForThisRun. Supply frontendOrigin for current loopback code; omit it for retained source.
• stop_capture — Stop one owned Capture and return its mandatory safe Review.
• stop_run — Close an owned replay and retain its safe run summary. A ready controlled page finishes verification; other active runs are cancelled.
• verify_fix — Fresh same-Card local Open after exact baseline target preflight (mismatch/unknown blocks before opening), ready wait, all baseline semantic criteria, optional owned visual evidence, terminal receipt and scoped delta. Nonsemantic obligations stay unsupported. A pending result resumes this exact sessionId; requestId deduplicates delivery. Does not run code or claim a visual verdict.

Agent-controlled Capture

Agent-controlled Capture is enabled by default when no preference is stored; explicit stored choices are preserved. Skills automatically call begin_agent_task using the original user request, bounded intent, source origins, selected Cards and local frontends. This authorizes necessary Capture, replay, Journey and protected login steps without repeated consent or global setting changes. Call end_agent_task when finished. Disconnect, task replacement and permission changes revoke that authority. Availability in the local MCP server does not install or automatically activate any coding-agent integration.

The agent-capture/1.0.0 lifecycle is limited to a managed Clean Session with authentication set to none. It can navigate, use bounded semantic controls, wait for visible state, stop into mandatory Review, save one ordinary State Card, or discard. It cannot use JavaScript evaluation, browser debugging protocols, screen coordinates, a Development Profile, generic credential retrieval, or protected values. An agent given login credentials for the task uses start_capture.credentials (username, password, optional expiresAt; default seven days) without repeated consent. StatePort creates the local protected reference. The agent follows the requested steps with fill_credential, an observed target.elementId, and field: username or password. Observe again after each action; observations cover allowed frames, open shadow roots and password metadata without field values. Legacy semantic targets and ticket input remain supported. Credentials never appear in responses or ordinary artifacts. Review is a required runtime step, not a new approval for an already requested Capture and Save. Permission revocation and client disconnect close active owned Capture pages; a durable Review receipt remains recoverable by its opaque captureId.

Page observation returns CAPTURE_OBSERVATION_TIMEOUT after five seconds without a result. Retry observation or discard the same Capture ID. Failed Stop is retryable; an exact durable failed Capture receipt remains discardable after reconnect. Discard never deletes a saved State Card.

Browser-launching MCP tools are headless by default and do not show a browser surface or ask for confirmation. A user can explicitly request a visible browser by passing browserVisibility: "visible" to start_capture or open_state; that choice remains bound to the session across runtime-owned reopen operations. Omitting the field, or passing "headless", keeps the browser hidden. Desktop-initiated workflows retain their normal visible default.

Results contain typed states, counts, origin/path, and bounded accessible names only. Fill and selection values, full page markup, request/response material, and local storage locations are excluded.

Reproduction outcome authority

stop_run returns the persisted terminal machine outcome for its accepted attempt. get_run_summary returns the safe qualified direct-run result, or an explicit legacy_unclassified compatibility result with reason LEGACY_RESULT_UNCLASSIFIED when older evidence lacks run-qualification/1.0.0. MCP does not infer success from browser or session lifecycle.

get_reproduction_outcome is an exact-attempt, read-only lookup. It never reconciles or changes an unfinished attempt. Every result includes top-level status, optional reason, attemptId, stateCardId, path, targetKind, and browserSessionMode. A bounded safe receipt is present only when verified run evidence exists; receiptless failures, unsupported results, and cancellations retain the trusted persisted status/reason and exact attempt context. A user_rejected result retains its machine outcome while exposing the same top-level context. Missing/nonterminal attempts return REPRODUCTION_OUTCOME_NOT_FOUND; unreadable or corrupt persisted evidence returns REPRODUCTION_OUTCOME_UNAVAILABLE. Neither error includes persisted content.

Request-change tools consume the same trusted request-change-evidence/1.0.0 as Desktop and CLI. They accept only the opaque evidence handle for an eligible exact remap; an agent-supplied exchange, origin, occurrence, or eligibility claim cannot grant replay or network authority. Captured-response remaps prove frontend behavior only.

Journey uses the original authorized task or explicit initiating-user confirmation. Interactive Recorded Journey remains under user control. All tool inputs are validated. Loopback Live routing must be explicitly selected for an inspected route.

Card transfer and Capture size

inspect_state_transfer previews a file or StatePort Share URL. import_state requires the same source, its expectedDigest, and confirmedByUser: true. Protected containers require cardOnly: true; protected acceptance remains in Desktop. export_state requires confirmedByUser: true and a file destination or kind: link. Link export uploads encrypted Card material and returns a full bearer URL; expiry accepts 1, 7 or 30 days (default 7). Existing files are never overwritten.

start_capture defaults to 1920 by 1080 CSS pixels, including visible Capture. Set viewport: { width: 1280, height: 720 } to override; both dimensions must be integers from 320 to 7680.

Compact Fix & Verify

At task entry, choose responseMode: text for one JSON text payload, or structured when the host exposes structured results to the model. Omission preserves legacy representation. Ordinary summaries are bounded to 16 KiB; get_run_summary, compare_runs and compare_run_checks accept detail: true. Persisted evidence is unchanged. Large default run reads preserve qualification/counts and an exact detail reference; large comparisons preserve comparability, total difference count and a byte-bounded sample with explicit truncation, including for legacy clients. Start with the default and request detail only for a missing diagnostic fact. Omitted differences do not prove equivalence.

begin_agent_task can prepare the exact Capture or Card; open_state(waitUntilReady: true) returns readiness and first observation in one call. Resume a pending session with its ID. Actions and checks support observeAfter; actions also support optional native visual evidence. Failed follow-up keeps actionPerformed: true. Reuse the same requestId only for an identical retry. Save returns Card identity and available readiness metadata without requiring another inspection. Optional save_capture.baseline takes an explicit loopback frontendOrigin, immutable descriptor and optional visual request to freshly Open and finish baseline on that saved Card. Review remains mandatory. Failure preserves Card/session; pending resumes the exact session and finishes, never repeats Save.

Semantic queries filter by safe name, kind, container and action. Rows may advertise click; Custom and Default controls retain safe grouping. allowRebind requires a unique compatible target without page replacement. Safe clientRoute identifies hash navigation independently of HTTP path.

list_visual_surfaces and capture_visual_evidence expose owned canvas or viewport PNG evidence, at most 4 MiB, with context/generation, dimensions and completeness. Viewports are bounded to 1920 by 1080; canvas dimensions to 2048 by 2048. Hidden, tainted, oversized, stale or protected surfaces return limited evidence. Images travel once as native image content and are not saved in Cards or logs. No other tab, profile, generic script or coordinate authority is added.

For action availability across button/link rendering, choose kind: control with an exact name and optional container before baseline; use strict button/link when role is required. New run-page-check/1.1.0 failures include a compact diagnostic and nextAction: TARGET_NOT_FOUND / inspect_target, TARGET_KIND_MISMATCH / review_criterion, or CONDITION_NOT_MET / inspect_behavior. Alternate-role evidence is diagnostic only, never automatic PASS or action authority. Unknown remains unknown. Compound baseline and candidate results retain these causes; resolve the named cause before repeating verification. Changed criteria require new original-code baseline and candidate evidence; old FAIL is not reinterpreted. Version 1.0 evidence remains readable without an inferred cause.

Verification descriptor version 2 includes semantic, visual and application-internal obligations. Missing criteria remain not_run; unsupported criteria remain unsupported. Visual evidence, agent assessment, semantic checks, runtime outcome and project tests are distinct. No enabled-button proxy proves a canvas criterion.

finish_run_verification records the contract on an existing ready owned Page, checks its semantic criteria, optionally returns a native image and stops with a run ID. It performs no page actions; criteria needing intermediate states still use granular checks. Visual and internal criteria retain unsupported status. Use it to retain baseline proof before edits.

verify_fix checks the integrity-verified baseline local target before fresh-opening the same Card/revision, then checks its semantic criteria, optionally captures an image, completes the run and returns scoped delta. Additional candidate actions use granular Open/actions/checks with optional open_state.baselineRunId to enforce the same early guard. Target drift returns blocked / BASELINE_TARGET_MISMATCH / opened: false with a validated baseline target; missing or nonlocal target evidence returns BASELINE_TARGET_UNAVAILABLE. Restart current code on the baseline target. Ordinary Open without a baseline retains intentional cross-target use. This preflight does not establish full comparison eligibility. The operation does not declare a visual PASS or verified fix. read_evidence_batch accepts up to eight exact run/check/console references, with independent statuses and a shared deadline/output budget. Stop after all material criteria are proved; unresolved gaps stay explicit.

Optional source context

get_capture_capability.contextBroker advertises an optional installed task-only source helper on supported Linux builds. The host authorizes local reads and invokes its product-owned command for prepare/expand/clean; MCP does not accept arbitrary source-reading commands. Use before broad source reads when useful, without Capture. MCP initialization includes compact source-routing guidance and scopes preparation to needed checks. Diagnostics add no task requirements; Capture retains browser state, not project builds. Direct query_source_context needs no discovery and returns compact stateport-context-query/2 snippets with exact paths/lines, short additional locations and explicit gaps; it creates no expansion handle. Already selected adjacent or overlapping source ranges may be combined without extra reads or inferred missing lines. Blocked queries set MCP isError; partial snippets are usable source with incomplete coverage. Existing prepare/expand contracts are unchanged. Bounded snippets are untrusted search matches, not runtime proof. Stale expansion fails closed; unavailable or insufficient context falls back to focused reads. This read-only utility grants no Capture/Open permission or entitlement. query_source_context also accepts purpose: "preparation" with a bounded failure: {summary, target?} after a missing module/stylesheet error. It returns stateport-preparation/1 with a declared workspace generator when supported; ready is a diagnosis, never execution proof. An absent explicit package entry with an unproven generator can return partial, next.kind=review_existing_script and GENERATOR_LINK_UNVERIFIED; the existing command is untrusted review context, not repair proof. Executable workflow failures can attach the same bounded diagnosis as workspacePreparation using their authorized workspace and an already observed missing-package error, avoiding a separate request without running scripts or retrying Capture. Owned-page Sass errors can expose one bounded relative import specifier as buildFailure.kind=missing_stylesheet, without raw errors, another browser or inferred workspace resolution. Capture/resume/recheck also return compact continuation evidence and named gaps; a saved Card with a timeout is not an established original assertion failure. A Capture failure before confirmed Save returns the current-attempt gap capture_save_not_confirmed, without making claims about older Cards. Source defaults remain v2; scope: source_only and limitations describe its boundaries, while gaps records search coverage limits. A source query does not make browser verification a pending requirement. The alternative helper mode inspect --workspace <project> --task <text> reads failure JSON from stdin. Neither path executes project scripts or creates a cache.

Behavior checks and response experiments

Discover get_run_page_capability before using replay controls. Skills use the original task through begin_agent_task without a separate replay prompt. Desktop also has a default-off Allow coding agents to check replay pages setting for direct clients. Controls require the exact ready Frozen session opened by this MCP connection; they cannot control an active Journey. Revocation, disconnect and replacement invalidate ownership. Observe before each bounded action/check; stale observations require a fresh observation. Negative checks require complete exact-target evidence.

describe_run_verification freezes safe agent-supplied case metadata and named criteria before checks. read_run_checks reads integrity-checked terminal evidence by run ID, including runtime-owned exact Card/revision identity and typed pass/fail/unknown checks separately from reproduction qualification. read_run_console reads that current run; read_console_evidence reads captured baseline evidence. Legacy evidence is unavailable, never assumed passing. compare_run_checks refuses changed conditions or unproved protected-context identity and reports same, changed or unknown from bounded actual served HTML/script bytes. This does not prove a commit identity. These checks do not assign a product Verified verdict.

For an ordinary Card, create_response_overlay applies one safe JSON merge patch to one source-bound exchange in a fresh session. Null deletes a key; arrays replace whole arrays. Hidden fields cannot be overwritten through a parent replacement. The terminal receipt distinguishes patched delivery from application consumption. Repeat with its exact patch and expectedSource; a changed source is rejected. Accepted tooling without delivery or UI consumption is not an exercised case.

A changed preview returns TRANSFER_CHANGED; inspect again before confirming. TRANSFER_FILE_EXISTS leaves the existing destination intact. TRANSFER_UNSUPPORTED_VERSION, TRANSFER_TOO_LARGE, and TRANSFER_INTEGRITY_FAILED reject incompatible, oversized, or damaged input before import. TRANSFER_PROTECTED_DECISION_REQUIRED requires the explicit Card-only choice or Desktop acceptance.