MCP server for agents

The Meticulous MCP server provides tools which enable agents to interface with Meticulous: get test run diffs, replay details, coverage, and more. It's a hosted Model Context Protocol endpoint, hosted at https://app.meticulous.ai/api/mcp. We furthermore provide agent skills which compose these tools into higher-level workflows, like a skill to review a PR test run.

• What it's for
• Connecting a client
• Authenticating with a token instead
• Available tools
• What this connector can access
• Troubleshooting
• Support and policies

Meticulous records real user sessions in your app and replays them against every commit to catch visual regressions before they ship. This server lets an agent — reviewing a PR, debugging a failing check, or investigating coverage — pull that data directly: which screenshots changed and why, whether a diff is a real regression or noise, which lines of a change are covered by a test, and (for CI/build agents) trigger a new run against a build.

The server is an OAuth 2.1 protected resource — it supports dynamic client registration and standard discovery (/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server), so clients connect with just the endpoint URL above. There is no client id, secret, scope, or authorization-server URL to configure by hand. Login happens in your browser on first connect and tokens refresh automatically.

For per-client install steps (Claude Code, Claude, Cursor, Codex, ChatGPT, VS Code, Devin, and org-wide connectors), see Setup.

Calls are scoped to your default project. If you only have access to a single project, that one is used automatically; otherwise set a default in your user settings in the web app, or via the CLI: meticulous auth set-project.

Any MCP client can also authenticate with a static bearer token instead of the browser OAuth flow — useful in CI, or wherever an interactive login isn't possible. The token is a Meticulous OAuth token or a project API token (see Setup > Choosing an approach for how to obtain one). A project API token scopes every call to that one project.

{
  "url": "https://app.meticulous.ai/api/mcp",
  "headers": { "Authorization": "Bearer <token>" }
}

Every tool takes broadly the same arguments as its matching CLI command and returns the same data as that command's --json output — with minor differences inherent to a hosted endpoint rather than a local CLI (for example, no git-inferred commitSha, since the server has no checkout to infer it from). "Access" below reflects each tool's MCP annotations, which determine whether a client can call it without per-call confirmation.

Results that are not ready yet

Every tool that reads a test run's or replay's results — get_test_run_diffs, get_test_run_diffs_counts, get_test_run_check, the four test-run coverage tools, and the replay-level get_replay_js_coverage and get_replay_diff_js_coverage_diff — returns { status: 'processing' } (the diffs list also { status: 'pending' }) while the test run or replay is still running, or while its result is still being computed after it finished, rather than an empty or partial result that would read as a finished one. Callers should poll the same tool every 10s until it returns the result, for up to 10 minutes. A failed result (with a reason) means nothing is still computing and retrying reproduces it.

For get_test_run_diffs, a poll can itself start the underlying compute workflow; that lazy compute does not make the tool a write. A completed get_test_run_check response is { status: 'complete', text }, or { status: 'complete', text, url } when the report is too large to return inline — text is then a short notice and the full report is downloadable from url. With checkType: 'custom', an error saying the run is not expecting custom check results can be transient shortly after the run completes, since your CI registers its checks separately from the run itself — this is usually resolved by retrying for a minute or so. Use get_test_run_check_available_ids to find a valid checkId instead of guessing one.

• Reads: your identity and the projects you can access; test runs and their status; reporting statistics and engagement events; screenshot diffs, outcomes, and images; DOM and timeline diffs; JavaScript coverage; and recorded session data (the user flow and network requests a session exercises).
• Writes (only when the corresponding tool is called): uploads a build's assets or container image, registers it as a deployment, triggers a new test run against it, changes your account's default project, and submits feedback to the Meticulous team.
• Never accesses: your repository's source code, or PR titles/descriptions — Meticulous's diffs and coverage are computed from screenshots, DOM snapshots, and instrumented JS execution, not from reading your code.
• Scope: every call is scoped to the projects the authenticated user (or, for a project API token, the single owning project) has access to.

• 401/403 on every call: your token has expired or was revoked — reconnect via /mcp (Claude Code) or your client's equivalent to re-authenticate.
• Claude Code: "Issuer mismatch in authorization response (RFC 9207)": Claude Code is reusing an authorization-server URL it cached from an earlier login. In /mcp, pick the Meticulous server and choose Clear authentication (not Re-authenticate), then Authenticate again.
• "No default project" errors: call set_project (list_projects shows the options), set one from your user settings in the web app, or run meticulous auth set-project — or, for a one-off call, pass the optional project argument most tools accept (id, org/proj, or simply proj; with an API token, only projects the token has access to — list_projects shows them).
• A lookup returns nothing when you expected results: it may have run against a different project. The default project is stored against your user account, so it is shared with the CLI and every other session, and changing it anywhere changes it everywhere. Call get_project to see which project is in play — an empty test-run or session result already names it for you.
• SSO-only organizations: if your organization enforces a specific identity provider, a token issued outside that flow is rejected; log in again through your organization's SSO entry point.
• Anything else: contact us (see below).

• Support: support@meticulous.ai
• Privacy policy: meticulous.ai/privacy-policy
• Terms of service: meticulous.ai/terms-conditions
• Security and compliance: security.meticulous.ai