Coding tools and Proof

Sign in to Proof and select your Organization. Ask your administrator for its HTTPS address. The example address https://proof.example.com is a placeholder. Replace it in each command with your Proof address. Keep /api/mcp at the end.

codex --version
codex mcp add proof --url https://proof.example.com/api/mcp --oauth-resource https://proof.example.com/api/mcp

codex mcp login proof --scopes proof:read,proof:setup,proof:author,proof:run,proof:audit

codex mcp list
codex mcp get proof

The Model Context Protocol (MCP) connects a coding tool to Proof. Browser OAuth lets you sign in and approve that connection without copying a password or token.

Ask your tool to open a Proof session with session_open. Use projects_list and environments_list to choose a website. A Project represents one website. An Environment is its named website URL and account settings. Select the exact Environment before you request work. Keep the returned session ID for later use.

Give Proof the feature, user role, steps, expected results, and exact assertion text. Assertion text is the text that the browser must find. State the intended behavior, even if the current website behaves differently. Your tool sends this through test_request.

Use Proof to create and verify a test in my selected Staging Environment.
Feature: account settings. Role: signed-in member.
Steps: open /settings and select Profile.
Expected result: the Profile page appears.
Exact assertion text: Profile settings.

A clear request creates and verifies the Test within existing permissions and spending limits. You do not need another approval for actions already permitted.

An unclear request saves a question. Answer it in your coding tool with operation_answer, or open Sessions in Proof. Select the request and complete Pending question. Both places use the same saved version. Refresh after a stale-answer error, then review the current question.

Complete existing coverage returns matching Test references. Partial coverage asks you to extend a selected Test or create a separate Test. New feature work keeps unrelated active Tests. Whole-project Mapping keeps its separate confirmation.

Review any new action permission before you approve it. Check the paths, controls, values, consequences, and use limits. Approve from either place with current write access.

Owners and administrators can use project_create, project_update, environment_create, and environment_update for permitted settings. Updates need the current resource revision. List the resource again after a revision conflict. Active work blocks Environment changes.

Use credentials_list to inspect account names and readiness. credential_create and credential_update manage this metadata. Use credential_setup_link to open the authenticated Proof form. Enter passwords and temporary codes only in the secure Proof form. Keep secrets out of tool arguments and chat. Setup does not increase action permissions or spending limits.

Use tests_list and tests_get to inspect saved Tests, expected results, and version IDs. Request tests_run with the exact Project, Environment, Test IDs, and matching version IDs. Keep each Test ID beside its version ID. Copy the IDs returned by Proof into this example:

{
  "sessionId": "COPY_SESSION_ID",
  "requestId": "saved-profile-run-1",
  "projectId": "COPY_PROJECT_ID",
  "environmentId": "COPY_ENVIRONMENT_ID",
  "testIds": ["COPY_TEST_ID"],
  "testVersionIds": ["COPY_TEST_VERSION_ID"]
}

Saved Runs use no AI inference and do not repair tests. Lists, status, results, and audit reads also use no AI inference. Browser execution can still incur charges. See Cost controls for the configured limits.

Use operation_get for progress and resulting Test or Run links. Use runs_list and runs_get for results and evidence. Open the same session in Proof to review questions, progress, and results. Measured model charges cover model use only. Reserved amounts are estimates. An unmeasured total is not zero.

Use session_events to read the redacted audit timeline. Audit replay reads saved history. It never runs the work again or captures your complete client conversation.

After a disconnect, use session_list or session_get, then read the existing operation. Do not submit a new request to check progress. Retry unchanged commands with their original request ID. Changed input needs a new request ID.

Use operation_resume only for eligible work, with its current version. Proof checks current access. A retry of the same browser job keeps its reserved spending. Each new paid job needs a fresh spending check.

Use operation_cancel or Cancel work to stop new work. An action already sent to a browser can still finish. Read the saved result for uncertain effects and cleanup.

The first version supports interactive browser sign-in. API keys and unattended automation are not supported for this MCP connection. A client connection cannot expand your Organization role. Viewers can read permitted data. Members can request and continue work. Setup requires owner or administrator access.

If sign-in expires, reconnect from the client. If Proof denies access, check the selected Organization, current membership, and approved permissions. Ask for the missing permission instead of copying another person's token. If the spending limit blocks work, inspect the saved result and ask your administrator to review the limit.

To clear the local connection, use your client's commands:

codex mcp logout proof
codex mcp remove proof

# Claude Code
claude mcp logout proof
claude mcp remove proof

Local removal can leave the server grant active. Proof advertises /api/oauth/revoke for clients that support token revocation. Do not extract tokens yourself. Proof checks server grants and current membership before new work. Revocation stops later browser actions. An action already admitted can finish.