AI Client Access (MCP)
QuantAssure exposes your compliance data to AI tools via the Model Context Protocol — so Claude, Cursor, or any MCP-capable client can query findings, risks, controls, and posture, and (with your approval) make changes, all under your organisation's permissions.
Before You Start
You need two things, and nothing else:
- A QuantAssure account that is a member of the organisation whose data you want to reach. If you can sign in to the dashboard and see your findings, you are ready.
-
An MCP client that supports remote servers over HTTP with
OAuth — Claude Code, Claude Desktop, and Cursor all do.
Clients that only support local
stdioservers cannot connect.
You do not need to create anything in advance. There is no "create client" button to find, and no client ID or secret for you to copy. Your AI tool registers itself the first time it connects, and you approve it in the browser. That approval is the moment access is granted, and it is the moment the audit trail records.
Your Endpoint
This is the only value you need:
https://production--quant-gov--quant-assure--4322.apps.quantgovsites.com/mcp Connect Your Client
Claude Code
Add the server, then start the sign-in from inside Claude Code:
claude mcp add --transport http quantassure https://production--quant-gov--quant-assure--4322.apps.quantgovsites.com/mcp
Then run /mcp in Claude Code and choose to authenticate.
Your browser opens to finish the steps below.
Claude Desktop, Cursor, and other clients
Add QuantAssure as a remote HTTP server in your client's MCP configuration:
{
"mcpServers": {
"quantassure": {
"type": "http",
"url": "https://production--quant-gov--quant-assure--4322.apps.quantgovsites.com/mcp"
}
}
} Restart the client. It will prompt you to sign in the first time it tries to use a QuantAssure tool.
What happens next
Whichever client you use, the sign-in is the same three steps in your browser:
- Sign in to QuantAssure. If you are already signed in to the dashboard in that browser, this is skipped. If not, you are sent to the login page and returned to the right place afterwards — so use the browser you normally use for QuantAssure.
- Review the consent screen. It names the client requesting access, shows the address you will be sent to after you approve, and lists every permission it is asking for. Nothing is granted until you approve here. A client that registered itself is marked "Unverified application (self-registered)", because anyone can register a client under any name. Check that the address is one you recognise. If such a client asks to change data, you must also tick a box confirming you trust that address.
- Approve. Your client receives its tokens and the connection is live. Ask your assistant something like "what are my open critical findings?" to confirm it works.
The consent screen is the only point at which a client is bound to your organisation. Until you approve, a registered client is just a name — it holds no access to anyone's data.
What You Are Approving
Access is divided into scopes — findings:read,
evidence:write, policies:write and so on —
and the consent screen lists exactly the ones being requested. A
client granted read-only access stays read-only.
If your role in the organisation is Viewer, the client gets read scopes only. Write scopes are left out of what you approve, and checked again on every request against your current role, so a client approved before you became a viewer loses its write access too.
Read the consent screen rather than assuming. A client that does not ask for specific scopes is given every read scope and no write scopes, so it can report on your data but cannot change it. Most AI tools do not request scopes explicitly, so this is the common case. A client that does ask for write scopes, which can create evidence, publish policies and trigger scans, has them listed on the consent screen as changes. If it asks for more than you want that client to have, decline.
Turning off write access for self-registered clients
Owners and admins can stop clients that registered themselves from ever holding write access. In Settings, open the Security tab and turn off Allow write access for self-registered MCP clients. It is on by default.
While it is off, a self-registered client is limited to read scopes however many it asks for. The consent screen says that write access will not be granted, and the token a client receives, including each refresh, carries read scopes only. A client approved earlier loses its write access the next time it refreshes, and an access token already issued keeps its scopes until it expires, within an hour. Clients an administrator registered for your organisation are not affected. Each change to the setting is recorded in the audit log.
Approval is per person. Your teammates each go through their own consent, and each of their clients acts as them. Everything a client does is attributed to the approving user in the audit log, including the approval itself, recorded with the scopes granted and whether the client registered itself or was registered by an administrator.
A client an administrator registers is for their organisation only. People in other organisations cannot approve it: the consent screen explains that it belongs to another organisation, and the refusal is recorded in the audit log. A client that registered itself is not tied to any organisation and can be approved from any of them.
Reviewing and Revoking Clients
Owners and admins can see every AI client with access to the organisation under Settings → Security → AI clients (MCP). The list includes clients an administrator registered and any client that someone in the organisation has approved, including clients that registered themselves. For each one it shows how many people approved it and when it was last approved. A client that registered itself can be shared between organisations, so the IP address and user agent it registered from are not shown.
Revoke removes every approval for that client in your organisation and revokes its refresh tokens. People who want to use it again have to go through consent again. A client that registered itself can be used from more than one organisation, and revoking it here does not affect any other organisation. A client an administrator registered for your organisation is deleted when you revoke it. Revocation is recorded in the audit log.
Revocation also stops access tokens the client already holds. Every MCP request is checked against the client's approval and the person's membership of your organisation, so a revoked client is refused within 30 seconds. The same applies when you remove a person from your organisation: AI clients they connected stop working for it within 30 seconds, their approvals and refresh tokens for it are revoked, and the removal is recorded in the audit log. If they are invited back, they have to approve each client again.
A client that registers itself but is never approved has no access. QuantAssure deletes it after 30 days.
If It Does Not Connect
| What you see | What it means |
|---|---|
| The browser never opens |
The client is not treating QuantAssure as a remote HTTP
server. Check the transport is http and the
URL ends in /mcp.
|
| "Authorization request not found or has already been used" | The link was already completed, or you opened it twice. Start the connection again from your client. |
| "This authorization request has expired" | Consent was left open too long. Start again and complete it in one sitting. |
| You are asked to log in and land on the dashboard instead of consent | Sign in first, then retry the connection from your client. |
| Tools work, then stop after a while | The connection is stateless: there is no session to expire, and each request stands alone. If tools stop working, your access token has probably expired or been revoked. Clients refresh automatically; if yours does not, reconnect it. |
What Clients Can Do
The tool surface covers the whole compliance conversation, not just lookups. A session with your assistant can move from "where do we stand?" to a generated audit pack without leaving the chat:
- Find the gaps — read tools list and inspect
findings (AI-adjusted severities included), risks, actions,
framework controls with your org's statuses, and posture
summaries.
get_posture_summaryreturns the same Security Posture score and A–F grade as the home dashboard and the email digest.list_findingsandget_findingsort and filter by the effective severity, and each finding carries two fields beyond its status:assignee({ id, name }, ornullwhen nobody owns it) andseverityOverride, present when a person overrode the AI's severity. It gives who, when, why, and the AI's own severity; the effective severity inaiAdjustedSeverityis then the person's. Overrides are read-only over MCP. - Triage findings (
findings:write) —update_finding_statussets a finding to new, open, dismissed or resolved, and the change is recorded in the audit log. Areasonis required to dismiss or resolve a finding, and to move a finding out of accepted (which ends its risk acceptance); an optionalnotesfield records more detail. It cannot setaccepted:accept_finding_riskdoes that, with areasonType(business risk accepted, false positive, mitigating control exists, or plan to fix), ajustification, and an expiry asexpiresInDays(30 by default) orexpiresOn, up to 730 days out. It creates the same risk acceptance, status change and audit entry as the dashboard. Accepting a risk is an accountable human decision: it needs a connection made through OAuth, and is recorded as the signed-in person. An API key (service token, including a support key) is refused with the codehuman_attestation_required; make the decision in the dashboard, or from an MCP client the person authorised.list_risk_acceptances(findings:read) lists acceptances soonest expiry first, filtered byfindingIdorexpiringWithinDays; each row isactive,endedorexpired. - Know when to trust the data —
get_posture_summaryalways carries acoverageblock reporting whether your connectors and collectors are healthy, so an agent never reports on your findings or posture score without also knowing whether the underlying collection is degraded.get_connector_healthdrills into the per-source detail — see Connector Health for what each status means and why it matters. - Check onboarding —
get_org_health(runs:read) walks the nine onboarding stages, from provisioning to a compliance target, and says whether each is done and when, where your organisation is stuck or waiting, the first recorded failure, and the latest connection check for each system. It only reads your organisation, and it reports people as counts: no member or invitee email addresses are returned. - Close them with evidence —
create_control_evidenceattaches evidence to a control (by code, e.g.ISM-1504), andupdate_control_status(which needscontrols:write, notevidence:write) records the applicability and compliance determination with a required rationale, captured in the audit trail. Evidence can carry an optionalurl(http or https) pointing at where the artefact lives. The rationale is stored as the control's applicability reason when you set applicability, and is otherwise kept in the audit trail. PassimplementationNotes(up to 10,000 characters) to record how the control is implemented; it is stored as the control's implementation notes, the same field the dashboard edits, and replaces any existing notes. - Update action items —
update_action(actions:write) edits an action and moves it through its statuses. Resolving, closing or cancelling an action, and reopening one from those statuses, are accountable human decisions: they need a connection made through OAuth and are recorded as the signed-in person. An API key (service token) is refused with the codehuman_attestation_requiredand nothing is changed; other edits are unaffected. The REST action endpoint applies the same rule to API keys (403). - Record and manage incidents —
create_incident,update_incident,add_timeline_eventand the finding and control link tools needincidents:write. Decisions that belong to a person — the notifiable data breach assessment and notification fields — are refused for a service token with the codehuman_attestation_required(the formeroverrideargument is gone). A connection made through OAuth sets them and is recorded as the signed-in person. Mistaken links are never deleted:unlink_incident_findingandunlink_incident_controlvoid a link with a required reason, hide it fromget_incidentby default, and keep it retrievable withincludeVoided. Bothcreate_incidentandupdate_incidentacceptexternalTicket: { id, url, system }to link the support case, GitHub issue or tracker ticket the incident is worked in. The url must be https, the change is audited, and onupdate_incidentpassingnullremoves the link. Support keys are read-only and cannot set it. - Exclude repositories deliberately —
list_connector_exclusions(connectors:read) shows the exclusions on a system (systemId), with who decided each, in what words, and whether its review date has passed. Exclusions are per system: passsystemId(the system that has the GitHub source configured). The exclusion applies only to that system's findings, and a system with no GitHub source is refused.connectorIdremains as an optional legacy anchor for exclusions made against a GitHub connector (org-wide by repo).create_connector_exclusionandend_connector_exclusionneedconnectors:write. An exclusion stops Dependabot and code-scanning alerts being ingested for repos matching a name or glob and retires the open ones already recorded, so the reply carries a retirement summary (batchId,matched,accepted,failed). It is an accountable human decision: it needs a connection made through OAuth, is recorded as the signed-in person, and carries their ownstatement. A service token is refused with the codehuman_attestation_required, andattestedByis no longer accepted. Retiring findings over MCP is capped: a matcher of*, or one that would retire more than 25 open findings, is refused with the codebulk_retirement_use_dashboardand nothing is changed; use a narrower matcher or do it in the dashboard. The review date can be at most 730 days away, and ending an exclusion needs a reason (a service token may end one). If a create reportsfailedfindings, callretry_connector_exclusion_retirement(connectors:write, same rules, nostatementneeded) to retire the remainder; it is safe to repeat and is refused once the exclusion has ended. - Check whether a message was delivered —
list_delivery_failures(notifications:read) lists failed email and Slack deliveries, newest first, filtered bysince(Unix seconds),channel,messageTypeandlimit. Each entry gives the channel, message type, status, a redacted error and the time. It never names the recipient, in any form. Records are kept for 90 days. - Author the policies behind the controls —
create_policydrafts a new policy from markdown, andupdate_policypublishes a revised version with a change summary. Revisions go through the same version history as the in-app editor: the previous content is archived as a snapshot, never overwritten.list_policiesandget_policyread the register, current content, and version history;list_policy_versionsandget_policy_version_diffpage through the archive and compare versions. - Run the policy lifecycle —
set_policy_statusmoves a policy between draft, active, under review and archived with the same audit event as the dashboard,record_policy_reviewrecords that a review took place, andupdate_policy_detailssets owner, approvers, effective and review dates and linked systems. Activating a policy is an accountable human decision: it needs a connection made through OAuth and is recorded as the signed-in person. An API key (service token) is refused with the codehuman_attestation_required; other status changes are open to it. There is no policy delete tool. - Run a fresh scan —
trigger_rundispatches a collection run for a system, through exactly the same path as the dashboard's run button. - Read the results —
get_run_statusfollows the run through collection and AI triage; once it completes, the read tools pick up the freshly triaged findings. A failed run includes itsfailurereason (for exampleheartbeat_lostortimed_out), andtriageSkippedsays when AI triage did not run. - Produce the audit pack —
generate_reportcreates any report type (AI Decision Audit Trail, SLA Compliance, and the rest), andget_reportreads back the summary plus a dashboard link to the full report.
Discovery tools return the IDs the other tools ask for, so an agent
never has to guess one: list_scopes and
get_scope (the system ID for trigger_run;
these tools keep their original scope names, which mean systems),
list_runs, list_reports,
get_asset, list_frameworks and
list_control_topics (the framework and topic filters for
list_controls), and list_threat_sources
(the threatSourceIds for risks). All are read-only,
limited to your organisation, and paged. Systems are read under
runs:read, and connector credentials are never included
in what they return. list_agent_jobs and
get_agent_job, also under runs:read, show the
AI jobs (triage, compliance analysis) behind a run: their status,
timestamps and how many items were delivered or failed, but not the
items themselves. The same scopes apply to the MCP resources:
assure://systems needs runs:read and
assure://frameworks needs controls:read.
Write tools also cover the day-to-day in between: create and update
risks and actions, update finding statuses, record a risk review
(record_risk_review sets the last-reviewed date to now,
moves the next review date on by the risk's review frequency, and
takes the reviewer from your login; an API key records no reviewer on
the risk, and the audit log names the key), and keep the asset
register current — list_assets reads the inventory, and
upsert_asset records an asset by its stable source
identity, so repeating the same upsert updates the existing record
instead of duplicating it (the same semantics the collection
pipeline uses). On an update, metadata is merged into
what is stored: keys you send overwrite, keys you leave out are kept,
and a key sent as null is removed. Every write is
audit-logged with your identity.
Errors and retrying
A failed tool call returns { "error": string, "retryable"?: boolean, "outcome"?: "not_applied" | "unknown" }.
Not-found, validation and constraint errors carry no flags: they will
not succeed on retry. When a database fault is transient the server
says which of two cases it is:
-
retryable: truewithoutcome: "not_applied"— the call failed before anything was committed (deadlock, lock wait timeout, no database connection available). Retrying is safe. -
outcome: "unknown"(neverretryable) — the connection was lost mid-request, so a write may have been committed. Read the current state (for example with the matchingget_orlist_tool) before retrying, or a create can be duplicated.
Other unexpected failures return a generic message with no flags and should also be checked before retrying a write.
Each tool group carries its own OAuth scope — for example
findings:read, evidence:write,
runs:write/runs:read,
reports:write/reports:read, and
connectors:read for get_connector_health and
connectors:write for connector exclusions, and
audit:read for list_audit_events and
get_recent_errors —
so the consent screen tells you which of these capabilities a client
is actually asking for.
Changing control status needs controls:write. update_control_status sets a control's applicability,
compliance status and implementation notes, which is your own
attestation. evidence:write now covers evidence uploads
and links only, and controls:write is granted only to a
signed-in person's MCP client. It is never available to an API key or
support key: creating a key with it is refused, and a key that somehow
lists it does not get it at request time. This is a breaking change
for existing clients. A client you approved with
evidence:write does not gain controls:write,
and update_control_status returns a Forbidden error until
the client is re-authorised and you approve the new scope. Agents that
used an API key for this tool can no longer do so; use a signed-in
client, or make the change in the dashboard.
The coverage signal on get_posture_summary is
deliberately not behind connectors:read: it lives under
the findings:read scope every existing client already
holds, so a client you approved before this feature shipped starts
seeing it with no re-consent required. It only tells
you counts — how many sources are degraded, failing, or have not yet
run. The named list of which sources are affected is more
detail than a findings-only client should get for free, so that list
— and the full per-source detail behind get_connector_health
— only appears once a client has been re-authorised for
connectors:read. Existing tokens can't pick this up
silently: the client has to go through consent again before either
the named list or the tool becomes reachable.
list_audit_events (audit:read) reads your
organisation's audit log, newest first: who changed what, plus
system events such as run outcomes (run.*), agent jobs
(agent_job.*), connector failures
(connector.*) and sign-ins. Filter by
entityType, an actionPrefix such as
run., and since (an ISO 8601 timestamp);
limit is at most 200. IP addresses and user agents are
never returned. audit:read is a read scope, so a client
that requests no scopes receives it; a client approved for an
explicit scope list before it existed must be re-authorised to use
the tool.
get_recent_errors (audit:read) lists the
server errors your organisation's users have hit, newest first: the
route template, method and status, the error name, a redacted
message, and the request id our engineers use to trace it. Filter by
since (an ISO 8601 timestamp) and a route
prefix such as /api/v1/orgs/[orgId]/findings;
limit is at most 100. Errors are kept for 14 days.
get_run_logs (runs:read) reads the
log lines for one run, oldest first, so an assistant can
explain why it failed or collected partial results. Each line has its
time, level, pipeline stage, component, and a redacted message and
error. Only lines for your organisation and that run are returned, and
lines that are not structured are left out. Filter by
stage (a stage id from get_run_status, such
as collect_github) and a minimum level
(info by default); limit is 200 by default
and at most 1000. A run that has only just started may have no logs
yet.
Autonomous Agents
Everything above assumes a person is driving — you sign in, you approve, and the assistant acts on your behalf. An agent that runs on a schedule or in a pipeline has no person to sign in as and no browser to open, so it uses a different credential: an organisation API key with API key scopes. The same scopes govern the key on MCP and on the REST API.
- Go to Settings → Security → API keys and create a key. Owners and admins only.
-
Tick the scopes the agent needs; at least one is required.
Read-only grants every read scope and nothing else.
The same scopes also limit the key on the
REST API, and some, such as
campaigns:readandcampaigns:write, so far only cover REST routes. Unlike an OAuth client, a key does not default to read-only. Keys created before scopes were required may have none: such a key has no MCP access. -
Give the key to your agent as a bearer token — no OAuth, no browser:
claude mcp add --transport http quantassure https://production--quant-gov--quant-assure--4322.apps.quantgovsites.com/mcp \ --header "Authorization: Bearer qa_your_key_here"
The important difference is in the audit trail. A person's assistant acts as that person. An agent on an API key acts as itself: entries appear under the key's name with an Agent marker rather than being attributed to whoever created the key. When an assessor asks who changed a control, "the nightly compliance agent" is a truthful answer and a borrowed username is not.
An API key is a bearer credential: anyone holding it has whatever you granted it, with no consent step in between. Grant the narrowest set of scopes that does the job, prefer read-only where the agent only reports, set an expiry, and revoke keys you are no longer using. Existing keys created before MCP support have no scopes and cannot reach MCP; create a scoped replacement rather than relying on them.
Support keys
A support key is an API key you issue so Quant Support can look at your organisation. Issuing it is your consent, and revoking it withdraws that consent. The key itself enforces the limits:
- It holds read scopes only. A support key cannot change findings, risks, evidence, policies or anything else.
- It must expire, at most 30 days after it is created.
- It works on MCP only. The REST API refuses it.
- Everything done with it appears in your audit log as Quant Support, with the support case reference when one is given. Every tool call and resource read is recorded as a
support.accessevent naming the tool and the ids it was given; if that record cannot be written, the call is refused and no data is returned. - Only owners and admins can create or revoke one, and both are recorded in the audit log.
Issue and revoke support keys, and review what Quant Support accessed, from Settings → Security → Support access. See Support Access.
Security Posture of the Endpoint
The MCP surface is hardened as a first-class product API: per-token rate limiting, stateless request handling (no long-lived sessions), CSRF-protected consent, request size caps, and org-scoped authorisation on every tool. Your data is only reachable with tokens minted through the consent flow you approved.
Every MCP action lands in the audit log — under the approving user's identity for a client you consented to, and under the agent's own name for an API key — so AI-assisted work carries the same accountability as manual work.