Recommend focused interface tests, launch approved runs, and retrieve evidence-backed results from the coding agent you already use.
Selectable endpoint; copy manually if needed.The endpoint is selectable text. Copy buttons appear when JavaScript is available. If clipboard access is blocked, select and copy the text manually.
Choose your coding agent.
Flock uses standard Streamable HTTP OAuth. Enter the environment-specific MCP URL, sign in to Flock, choose a workspace, and review the requested access before allowing it.
01
Codex
Add the Flock MCP URL; Codex opens Flock sign-in and consent without manual client or callback settings. The optional server block below gives a cold backend longer client-side MCP waits while keeping URL-only OAuth.
The 350-second values are only MCP server initialization and tool-call budgets. They are not OAuth browser login, token exchange, or refresh timeout controls, and they do not fix or prove OAuth cold-start latency. Normal URL-only setup does not require them. Review the access requested by your client on Flock consent. Keep this environment in its own flock-prod entry so another Flock environment is not overwritten.
02
Claude Code
Add the Flock MCP URL for normal setup, or use the optional JSON alternative to pin the connection to read-only access. Claude Code opens Flock sign-in and consent without a manual client ID or callback port.
Claude Code Add by URL
claude mcp add --transport http flock-prod "https://mcp.flocksynthetics.com/mcp"
Claude Code Optional read-only setup
claude mcp add-json flock-prod \
'{"type":"http","url":"https://mcp.flocksynthetics.com/mcp","oauth":{"scopes":"https://mcp.flocksynthetics.com/mcp/read"}}'
Claude Code Sign in to Flock
claude mcp login flock-prod
Claude Code supports a space-separated oauth.scopes value; the read-only alternative keeps automatic client identity and callback selection. Flock consent approves or denies the scopes the client requested; it does not choose them. If flock-prod already exists, update that entry rather than adding a duplicate and keep each Flock environment distinct. Changing the configured scopes or refreshing a token does not expand an existing grant. Request feedback alongside any access you intend to keep, then reconnect or reauthorize and approve the new requested access. If Claude Code keeps reusing the old grant, disconnect that specific connection in Flock Settings → Connected tools, then reconnect.
03
ChatGPT and Claude
In ChatGPT or Claude connector settings, enter the Flock MCP URL. Sign in to Flock, choose a workspace, review the requested access, and select Allow access.
ChatGPT and Claude configuration
MCP URL: https://mcp.flocksynthetics.com/mcp
URL-only setup supports ChatGPT, Claude, Codex, and Claude Code. No arbitrary dynamic client registration is supported. The browser returns to your client after authorization. Each connection belongs to the workspace you approved.
Hosted server, local CLI sign-in.
The server endpoint, OAuth callback, and page you review are three different addresses.
The MCP server is hostedConnect to https://mcp.flocksynthetics.com/mcp. This HTTPS endpoint is Flock's hosted service; it does not run on your computer.
The CLI sign-in callback is localYour CLI starts a temporary local listener and chooses the callback used by its URL-only OAuth flow. The browser returns to that listener after Flock sign-in and consent. A hosted MCP endpoint and a local OAuth callback serve different purposes; normal URL-only setup does not need manual client or callback settings.
Remote shells need a reachable callbackIf your browser and CLI run on different machines, or the CLI runs through SSH, a container, or WSL, the browser's localhost may not reach that listener. Run sign-in where the browser can reach the CLI listener, or intentionally forward the callback port supplied by your client through a private connection. A custom Devbox or proxy callback URL is not automatically supported by the client’s URL-only OAuth flow. Do not expose the callback listener publicly.
Hosted clients have a separate callbackChatGPT and Claude use their own hosted connector callbacks rather than your CLI’s local listener. Enter the Flock MCP URL in the client’s connector settings and follow its connection flow; availability still depends on the client and workspace settings.
The page you review needs its own reachable URLA review target such as http://localhost:3000 is a separate issue: a hosted Flock runner cannot reach a server on your computer through your localhost address. Use a preview or deployment URL that the runner can reach. Completing MCP sign-in does not make a local or private application reachable.
Flock asks your agent to offer guided setup when it can respond. Whether the welcome appears immediately depends on your client.
The welcome can look like this:
Welcome to Flock. Want help setting up this project and choosing a useful first review?
Your agent can guide setup from here. You do not need to paste a procedure or know the tool names.
If your client does not show a welcome
You can use this short request. The agent can call get_setup_guidance for the setup workflow; clients that expose MCP prompts can also select flock_onboarding.
Setup request
Set up Flock for this project and help me choose a useful first review.
Other optional requests
Plan a review
Use Flock to recommend and estimate a review of [URL] for [user journey]. Do not launch it yet.
Continue this project
Use our FLOCK.md to plan the next review. Check what has changed and show me the proposal.
Investigate a review
Investigate my latest failed review. Explain the findings and show me the available evidence and repair prompts.
Product concepts
Integration guides
Your agent can search the public documentation with search_product_docs and read a result with get_product_docs.
Advanced agent reference
From your project to a first test.
Use get_setup_guidance with read scope. The optional flock_onboarding prompt offers the same workflow in clients that expose prompts.
Start hereCall get_setup_guidance with no arguments using read scope for the live onboarding guidance, supported configuration examples, and dashboard links. Clients that expose MCP prompts can also select flock_onboarding with no arguments. The tools-only path is authoritative for clients that do not expose prompts; onboarding does not require prompt support or test scope. Use the live Core guidance and catalog rather than inventing configuration fields.
Understand this projectThe agent may inspect local files only through its existing client permissions and tools; no special client or plugin install is needed for the local scan. Flock MCP does not read your filesystem or obtain GitHub repository credentials. Read a bounded selection of README files, package manifests, routes, auth boundaries, and existing tests; skip .env files, secrets, and generated directories, and do not execute unknown scripts. Present facts with relative file evidence, assumptions, and unknowns, then invite corrections. Distinguish observed source facts from runtime observations, user statements, and assumptions. With no file access, use honest user-supplied context and offer the Flock README text for the user to save.
Choose one useful first testOffer 2–3 small project-grounded test choices, explain the value and boundaries of each, and choose one first test with the user. account and workspaces return a grant-filtered directory: confirm the authorized workspace name and ID. If the intended workspace is missing, guide reauthorization rather than silently changing workspaces.
Choose access explicitlyDiscover saved sign-ins with list_auth_profiles and choose anonymous access or an explicitly selected compatible saved sign-in. recommend_test_configuration uses only supplied context and the catalog; it does not inspect the app. Preserve the exact authentication selection through recommendation, estimate, and launch. Treat current readiness, historical verification, and usage eligibility separately. Missing or stale profiles require the browser setup or reconnect flow before proceeding; never silently fall back to anonymous access.
Complete saved sign-in in the browserUse the dashboard URL returned by list_auth_profiles or get_setup_guidance to open Settings → Integrations (/settings/integrations). Select the same authorized workspace in the dashboard before Add saved sign-in or Reconnect. Choose Add saved sign-in, enter a Sign-in name and the signed-in App URL (not the login URL), then choose Open sign-in. The human completes login and MFA in the browser and chooses Check sign-in until connected. For an existing profile, use Reconnect; use Sign in directly when the browser flow offers that fallback. For an explicitly selected existing profile, start_auth_profile_reconnect opens a safe first-party human handoff; get_auth_profile_reconnect_status reads current status and cancel_auth_profile_reconnect cancels it. Starting or cancelling requires test scope and current workspace owner or admin access. Use the same Flock account and selected workspace in the handoff. MCP cannot create profiles or complete app login and MFA. Reconnecting never launches a review: refresh setup, authentication readiness, and the estimate, then obtain explicit launch approval. Do not ask for Kernel keys or copy browser state into chat.
Approve the bounded runUse estimate_run for the exact bounded configuration. Show the target URL, workspace name and ID, persona, allowed and prohibited actions, production classification, authentication choice, and expected units. Explain readiness and usage separately. Obtain explicit approval unless the conversation already approves this concrete run. launch_run requires test scope, workspace policy eligibility, and a unique caller idempotency key. Follow status, retrieve ready results, review technical findings and evidence images, and retrieve every available canonical repair prompt.
Your Flock README.
Keep reusable project context in FLOCK.md and refresh live facts before every run.
Keep agreed project knowledgeThe client writes repo-root FLOCK.md titled Flock README with agreed project context, reusable test recipes, source basis and revision, relative file paths, corrections, and workspace/profile IDs as references only. Preserve user-authored material and mark unconfirmed additions as proposed. This file is project knowledge, not a server-side memory store. No AGENTS.md or CLAUDE.md rewrite is required.
Refresh before reuseAt the start of subsequent Flock tasks, read repo-root FLOCK.md using existing client permissions, recheck relevant source and working-tree changes, and refresh changed context. Revalidate live workspace authorization, saved sign-in readiness, catalog options, and the exact estimate. Never store credentials, tokens, cookies, capture URLs, or authentication state; never persist launch approval as authority for a future run. Current conversational authorization may cover a concrete bounded launch; a saved README never does.
A careful workflow
Connect and review the requested access. Read, test, and product feedback use separate scopes.
Call get_setup_guidance with no arguments; optionally select the flock_onboarding MCP prompt. Discover or create the Flock README in repo-root FLOCK.md.
Confirm the account and choose the workspace to use.
If the target needs authentication, choose a compatible saved sign-in explicitly. Treat current readiness, historical verification, and usage eligibility as separate facts; if the profile is unavailable or ambiguous, ask me to choose or reconnect it instead of falling back to anonymous access.
Describe the application URL and the user journey; ask for a recommendation.
Review readiness and the estimate, then explicitly approve a launch.
Launch with a unique caller idempotency key and retain the receipt.
Follow lifecycle status, then retrieve results and inspect available evidence images.
What the tools cover
submit_feedbackSend text-only product feedback to the Flock team. Requires https://mcp.flocksynthetics.com/mcp/feedback; this does not grant permission to launch, retry, or cancel tests. To add feedback to an existing connection, request feedback alongside any access you intend to keep, then reconnect or reauthorize and approve the new requested access. Refreshing a token does not expand an existing grant. Read and feedback allow feedback without test authority; request read, test, and feedback to retain both test and feedback access.
search_product_docsSearch the public documentation with query and optional limit (1–5). Use the returned canonical document id with get_product_docs to read a result. Search covers public product concepts and integration guides, not private workspace data.
get_product_docsRead a public guide by topic, or by a canonical id returned by search_product_docs. Supply only one of topic or id. Read scope is sufficient; no workspace ID is needed. Use it before explaining product concepts or configuring an integration.
get_setup_guidanceRead live onboarding guidance, supported configuration examples, and browser dashboard links with no arguments and read scope.
account, workspacesConfirm the signed-in account and selected workspace.
list_auth_profilesList the authorized saved sign-in inventory and choose a compatible profile explicitly. Current readiness, historical verification, and usage eligibility are distinct; never paste passwords, tokens, cookies, or browser storage into chat.
start_auth_profile_reconnect, get_auth_profile_reconnect_status, cancel_auth_profile_reconnectStart or resume a reconnection for workspace_id and auth_profile_id with an idempotency_key, read bounded current status using reconnect_id, or cancel it. Open only the returned first-party handoff; human login and MFA stay in the browser. Reconnect never launches a review.
recommend_test_configuration, estimate_runSuggest a context and catalog from the authorized inventory, then report current readiness and expected usage without treating historical verification as current readiness or an estimate as usage authorization.
launch_run, get_run_status, get_run_resultsRun an explicitly approved test, follow its batch lifecycle, and retrieve actionable findings plus bounded image descriptors.
get_run_imageRead one actual run image from an opaque descriptor returned by get_run_results, with safe attribution metadata.
retry_run, cancel_runRequest cancellation with a durable receipt, or retry an eligible failed run with its frozen configuration when test scope and workspace policy allow it.
list_reviews, get_latest_review, get_reviewRead workspace reviews with bounded findings and run references; use get_run_results for a returned run.
get_review_evidenceRetrieve bounded screenshot handoffs and safe technical evidence for a discovered review finding.
Agent guide
Product documentationSearch with search_product_docs using query (1–256 characters) and optional limit (1–5, default 5). Read a result with get_product_docs using its canonical id; do not send id and topic together. Use topic scores, findings, concepts, mcp, or github for a guide, or resources flock://docs/scores, flock://docs/findings, flock://docs/concepts, flock://docs/mcp, and flock://docs/github. Check the response source and stale or fallback metadata. These are read-only public guides, not workspace results or permission to launch a review.
get_setup_guidance / flock_onboardingget_setup_guidance is a read-only tool with no arguments. flock_onboarding is an optional MCP prompt with no arguments, not a tool. Use get_setup_guidance as the authoritative tools-only path. These guide the agent; local inspection and FLOCK.md edits remain client operations under existing permissions.
recommend_test_configurationCall with workspace_id, url, and goal. It is a context and catalog heuristic; it does not inspect the application. For authenticated targets, pass authentication with intent saved_sign_in and the explicitly selected auth_profile_id when known. If several compatible profiles remain, ask the user to choose. Use intent anonymous only when anonymous access is intended; never silently substitute it for blocked saved sign-in.
estimate_runCall with workspace_id, url, and the proposed configuration. Do not add idempotency_key; its schema does not accept one. Explain current launch readiness, historical verification, and expected usage separately; an estimate does not authorize usage.
launch_runSupply a unique caller idempotency_key and the explicitly selected saved sign-in when authentication is required. If the response is uncertain, replay the exact same payload and key; do not silently retry anonymously.
retry_runRetry only an eligible failed run with its frozen source configuration. Supply workspace_id, batch_id, and a unique caller idempotency_key. If the response is uncertain, replay the exact same payload and key; do not create a new key for transport recovery. Follow the safe error code together with source_status and next_action when rejected: wait for an active run to reach a terminal state, start a fresh review for a completed run, or reconnect the saved sign-in before explicitly starting a fresh review with a new key. Frozen-config retry does not repair auth_profile_reconnect_required. A v2 multi-target retry is safely rejected with review_multitarget_retry_unsupported and does not rerun successful siblings.
cancel_runSupply workspace_id and batch_id, then read cancellation_receipt rather than treating the top-level cancellation status as the receipt. receipt_status is accepted, already_requested, terminal, or outcome_uncertain. durable is the boolean for whether the cancellation request was actually saved; terminal is true only for an observed terminal state; propagation_status is confirmed, uncertain, or not_checked. Use the exact cancellation_receipt.status_read action and arguments for get_run_status when the outcome or propagation is uncertain. Acceptance is not terminal completion. A known durable save remains durable through a downstream publication or read failure and must not be reported as rejected. outcome_uncertain requires get_run_status before deciding, and repeating cancellation is safe; never launch a replacement merely because a response was lost.
get_run_status / get_run_resultsStatus uses workspace_id and batch_id; results use workspace_id and run_id. Check lifecycle before treating results as final. Results report images_status as available, not_ready, or unavailable, with images_reason and images_retryable. Available images include opaque artifact_id, kind, label, content_type, size_bytes, origin_scope, and optional source_step.
get_run_imageUse only workspace_id, run_id, and an artifact_id from get_run_results.images. Success returns native MCP image content plus structured status available and safe attribution metadata. Read failures are isError results with structured status not_ready or unavailable, reason, and retryable. Images are bounded to 8 MiB without truncation. Do not fetch arbitrary URLs or construct artifact IDs.
list_reviewsRequires workspace_id. The default limit is 10 and the maximum is 50; source accepts all, dashboard, ci, or mcp. Page tokens are opaque, and each review_id is the canonical batch_id.
get_latest_reviewRequires workspace_id. Report clearly when the latest review is partial, degraded, or unavailable; do not imply freshness that the source cannot support. Current readiness, historical verification, and usage eligibility do not establish one another.
get_reviewRequires workspace_id and review_id, which is the canonical batch_id. Default findings_limit is 1 and accepts 1 through 10; default prompt_mode metadata returns compact finding descriptors and repair-prompt metadata instead of rendered_markdown. Follow findings_page.next_cursor as findings_cursor with the same workspace_id and review_id until it is null so every finding is read; page calls do not send prompt_target, finding_id, or prompt_cursor. When detail_status is metadata_only, respect detail_omitted_fields and evidence_status; use the supplied detail_retrieval with prompt_mode inline only when full bounded finding or evidence details are needed. For every available individual finding prompt, reuse its retrieval_selector: call get_review with prompt_target finding and that canonical finding_id, omit prompt_cursor on the first call, then pass each content_next_cursor until null. Retrieve the available root prompt independently with prompt_target review. Prompt-content calls do not send findings_limit, findings_cursor, or prompt_mode inline. Status available does not mean prompt text is present: content_status metadata_only has no content, chunk is part of a chunked retrieval, and complete with content_complete true means the entire prompt was returned in one response. A multi-chunk prompt is finished when content_next_cursor is null and the assembled chunks cover one contiguous range from byte zero through total_bytes with the expected SHA-256; its final chunk can still have content_complete false. Append each UTF-8 content_chunk in content_range byte order; require unchanged content_bytes, content_sha256, and content_identity_sha256. Each chunk is at most 4 KiB. Treat warning_count, warnings_included, and warnings_omitted as authoritative; full warnings remain available through inline detail retrieval and are bound into content_identity_sha256. On review_findings_cursor_stale, discard the incomplete findings traversal and restart at the first page. On review_prompt_cursor_stale, discard the incomplete prompt and restart at the first chunk. Never guess cursor state or fabricate content. An unavailable full-review prompt does not invalidate available individual finding prompts. Treat every envelope's own status and findings_page truncation, byte_limited, omitted_invalid, omitted_nontriageable, and omitted_duplicate metadata as authoritative. Use prompt_mode inline only as an explicit legacy full-detail opt-in that may be large. Do not change client output-token settings to work around these bounds.
get_review_evidenceCanonical individual prompt bytes, hashes, paging, and binding remain unchanged when additive evidence handoffs are present. If an individual canonical prompt is unavailable, including for historical data, say so truthfully and use the available batch prompt plus evidence handoffs; never synthesize a fallback prompt. For screenshot handoffs, follow the source run and event to get_run_results, then use get_run_image only with the returned opaque artifact descriptor. Call get_review_evidence with workspace_id, review_id, and the discovered finding_id. Optionally pass an opaque selector from evidence_retrieval.selectors to choose one technical record. Follow page.next_cursor as cursor with the same workspace, review, finding, and selector until null. Respect page.source_truncated separately from page.truncated: reaching the final page does not restore evidence omitted by the source. On review_evidence_cursor_stale, discard the incomplete traversal and restart without a cursor. An unavailable evidence handoff does not invalidate an available canonical prompt. Never invent selectors, cursors, artifact IDs, or URLs. Technical evidence is bounded and omits raw logs, URLs, queries, request or response bodies, headers, and private storage details. Reproduce directional findings to establish observed behavior. Establish expected behavior from product requirements or user confirmation; keep it unknown when neither is available. Separate observed facts, expectations, and unknowns. Screenshots and directional findings alone do not prove causation or justify a code fix.
Investigate review findings.
An agent with read-only access can discover the workspace and latest review, inspect lifecycle and technical findings, use available full-review and individual canonical repair prompts, and read bounded evidence images without dashboard URLs or supplied IDs.
Review example 1
List reviews for workspace_id [WORKSPACE_ID] with the default limit of 10, source mcp, and opaque paging.
Review example 2
Get the latest review for workspace_id [WORKSPACE_ID] and say plainly if the result is partial, degraded, or unavailable.
Review example 3
Get review_id [BATCH_ID] for workspace_id [WORKSPACE_ID]. Follow every findings_page.next_cursor, retrieve every available individual repair prompt through its ordered content chunks, verify its byte length and SHA-256, then use get_run_results for a returned run.
Review example 4
Investigate my failed review without asking me for IDs. Discover the account and workspace, find the latest review, explain its lifecycle and technical findings, traverse every findings page, retrieve and verify every available canonical repair prompt, retrieve related run results only when ready, follow evidence handoffs from source run and event to opaque screenshot descriptors, and inspect its evidence images.
Review example 5
Review directional findings conservatively: identify actual observed behavior, expected behavior, and unknowns; reproduce observed behavior and establish expected behavior from product requirements or user confirmation, keeping it unknown if unavailable; do not treat screenshots alone as causal proof or justification for a fix; and use the batch prompt and evidence handoffs when an individual historical prompt is unavailable.
Permissions and usage
Read scopeProduct documentation, account, workspaces, recommendations, estimates, status, results, workspace review reads, bounded review evidence, and manifest-bound run images.
Test scopeLaunch, retry, cancel, and start or cancel saved sign-in reconnection, subject to current selected workspace policy and permissions.
Sign-in profilesChoose a compatible saved profile explicitly when a target requires login. If readiness is ambiguous or unavailable, choose or reconnect a profile; never silently fall back to anonymous access or share credentials or browser secrets in chat.
EstimatesAn estimate describes expected usage. It is not a monetary guarantee or a claim that a run is free.
Recover safely
If a launch or retry response is interrupted, replay the exact same payload with the original unique idempotency key to recover the receipt. Do not create a new key for transport recovery.
For cancellation, distinguish durable acceptance from terminal completion. An uncertain receipt requires the returned exact status read and a safe repeated cancellation; do not launch a replacement while the outcome is unresolved.
Reconnect a saved sign-in before explicitly starting a fresh review with a new key when the source reports auth_profile_reconnect_required. Sign into Flock only when the agent opens a Flock authorization prompt. A workspace invitation may be required before consent.