DocsIntegrations

Test controls with your own AI assistant

Updated 2026-10-07

By Adam Swenson · 15 September 2026

You can now perform a control test with the AI assistant you already use, whether that is Claude, GitHub Copilot, Cursor, or ChatGPT. You then submit the result to Zovos as evidence for that control's test period. Your assistant fetches the published procedure, runs the test with its own tools against your own system, and hands the result plus the raw output back to Zovos. There it lands pending human review. This is the Zovos Evidence Protocol (ZEP). It consists of an open submission contract, a published result schema, and a set of tools. Zovos never builds glue into your systems and never receives your system credentials.

This is for the compliance owner or tester who runs a control test today in the Zovos UI and wants to run it from the assistant on their own machine instead. It does not replace the reviewer. No external result changes a rating until a different person accepts it.

  1. Fetch the procedure. Ask your assistant to call query_controls with include_procedure=true. It returns the control, its acceptance criteria, the expected evidence, population and sampling guidance, and the current procedure_version. A due-for-testing filter finds the work that is actually open.
  2. Run the test with the assistant's own tools, on your system. The assistant gathers the evidence with its own shell, scripts, and connectors, which are already authenticated to your environment. Zovos supplies no probes and touches nothing on your side. Save the raw output to a file.
  3. Submit the result and artifacts. The assistant uploads each evidence file out-of-band through a presigned upload, so the bytes never pass through the model or the transport. It then calls submit_control_test_result. Call it first with confirm=false to see the dry-run, then again with confirm=true to record it. The submission enters pending_review.
  • The tester of record is you. That means the verified person behind your Zovos login, derived server-side from your sign-in. It is never something the assistant declares.
  • The assistant is self-declared and shown UNVERIFIED. Its name, model, and version are recorded verbatim as metadata and are never an authorization signal.
  • Raw tool output is required. A submission whose method is TEST or AUTOMATED must carry at least one raw_tool_output artifact. A narrative alone is not evidence. A fail or pass-with-exceptions outcome must also list at least one exception. There is deliberately no confidence field, because a model could fabricate a stated confidence. Assurance comes instead from the raw artifact, its server-computed hash, an append-only audit, mandatory review, and random re-testing.
  • A human distinct from you accepts it. On acceptance the outcome maps to effectiveness. Pass maps to Effective, pass-with-exceptions to Partial, and fail to Ineffective. Not-tested and not-applicable never change a rating. Acceptance also means the control owner's attestation cadence is satisfied for that period. Until acceptance, attestations stay manual to the owner.
  • A failed test opens a draft Finding. On accepting a fail or pass-with-exceptions, each exception becomes a draft Finding and linked risks are re-flagged.
  • Some accepted submissions are re-tested at random. By default 5 % of accepted submissions are flagged for a re-perform. Your administrator can move that anywhere from 0 to 100 %. A mismatch is recorded on both the control and the submission.

Your system credentials never go to Zovos. You authenticate to your own system with your own credentials on your own machine. Zovos receives only the result and the artifacts you attach.

Never upload:

  • Do not upload credentials, tokens, API keys, cookies, or connection strings. Strip them before upload.
  • Do not upload SAR, BSA/AML, or CTR content. It is legally confidential and must never be submitted.
  • Do not upload customer PII beyond the minimum the control requires. Redact where you can.

Zovos enforces this on top of your care, not instead of it. Every uploaded artifact is content-sniffed and malware-scanned, and archives are expanded and scanned member by member. Every artifact then runs through a credential / PII / SAR classifier.

  • A credential or SAR/CTR match is refused. The upload is rejected, and the error names the pattern class, never the matched secret. A reviewer cannot override a refusal.
  • PII at or above a threshold is quarantined. It is stored but download-blocked, and it is flagged for a reviewer.

The skills enforce one more habit. Summarise counts in context and attach the full file out-of-band, so sensitive raw content stays out of your assistant's model context.

Evidence is referenced by sha256 and uploaded with a presigned PUT. Zovos re-computes each hash server-side and rejects any mismatch. Give each file a role: raw_tool_output, screenshot, export, transcript, or supporting. The allowed types are PDF, PNG, JPEG, plain text, Markdown, CSV, JSON, XML, ZIP, XLSX, and DOCX. The cap is 50 MB per file. A text-only client with no local files can instead pass an inline_text transcript up to 32 KB.

There are two ways in. Most assistants speak the remote connector directly over OAuth. Claude Desktop and ChatGPT cannot run a local test on their own, so they use the local bridge. The coding-capable clients can both test and submit.

This section is the shared setup for every Zovos AI-assistant connection. The full per-client walkthrough for Claude, ChatGPT, Cursor, Copilot, Gemini, and the local bridge is in Connect your AI assistant. The steps below are the ZEP-specific companion.

Point the client at the Zovos MCP endpoint and sign in with your Zovos account when prompted:

https://app.zovos.ai/api/mcp

ClientWhere to add it
Claude Codeclaude mcp add --transport http zovos https://app.zovos.ai/api/mcp
Claude.ai / Claude DesktopSettings → Connectors → Add custom connector → paste the URL
Cursor.cursor/mcp.json → an mcpServers entry of type http with the URL
VS Code Copilot.vscode/mcp.json → a server of type http with the URL
ChatGPT (developer mode)Settings → Connectors → add an MCP server with the URL

Your access token is short-lived. A well-behaved client refreshes it on its own, so a long test does not stall. Select your organization at sign-in. A session with no organization selected is refused with a message telling you to pick one.

Some clients cannot run the test themselves, such as Claude Desktop and ChatGPT. For those, the zovos-mcp bridge runs on your machine and logs you in with a device flow. It also adds a local upload_artifact_file helper that does the presigned upload MCP cannot do on its own.

  • npx zovos-mcp login authorizes the CLI with your Zovos login.
  • npx zovos-mcp starts the local server. Point your assistant at the command npx -y zovos-mcp.
  • npx zovos-mcp doctor checks reachability, your token, and the tenant flags.
Availability. The zovos-mcp package publishes to npm when Zovos announces the Evidence Protocol. The commands above are how it will read once it is published.

Whichever path you use, the bridge and the connector share the control-testing tools query_controls, submit_control_test_result, and get_submission_status. For evidence files, the connector exposes begin_artifact_upload and commit_artifact, and the bridge replaces both with its single upload_artifact_file helper.

An administrator enables this per workspace under Settings → Integrations → AI assistants. It is off until they opt in. Your account also needs a verified email, and a sign-in without one is refused. The re-test sampling slider (0 to 100 %, default 5 %) lives on the same screen.

Load the skill pack for the control's family first, then ask in plain language. These three prompts exercise the read tool, the submit tool (dry-run then confirm), and the status tool.

  1. Find work and fetch a procedure. "Using the Zovos tools, list the controls that are due for testing this quarter, then fetch the full procedure package for the MFA-on-privileged-accounts control so we can run it."
  2. Run, dry-run, then submit. "Run the asset-inventory procedure against our CMDB with your own tools, save the raw export, and upload it as raw_tool_output. Then call submit_control_test_result with confirm=false and show me the dry-run. I want to see the mapped outcome, the exception count, and whether it would satisfy the owner's attestation. After that, resubmit with confirm=true."
  3. Check the reviewer's decision. "Check the status of that submission with get_submission_status and tell me whether the reviewer accepted it, requested changes, or flagged it for a re-perform."

Always review the dry-run before you confirm. The assistant should never submit silently.

Once a submission is accepted, an examiner or your team can export it in two open shapes without the assistant ever having to emit them. OSCAL Assessment Results serve OSCAL-speaking programs, and OCSF Compliance Finding records serve a security data lake. Both are generated server-side from the same sealed submission, one per submission or batched across a control's test period.

  • The access token carries no organization. Sign in again and choose your institution. Zovos never defaults you into one.
  • This organization has not enabled ZEP control testing over MCP. An administrator has not opted in yet. The switch is ZEP control testing in Settings → Integrations → AI assistants.
  • The access token's email address is not verified. Verify your email with your identity provider, then sign in again.
  • The procedure version was rejected (409). The procedure moved under you. The error hands back the current package. Re-run against it and resubmit.
  • An artifact was refused. The classifier found a credential or SAR/CTR pattern. Remove it and resubmit. A reviewer cannot override a refusal.