AI assistants (MCP)
People in your company can connect the AI assistant they already use to your Proofroom and ask it about their compliance work: “How ready are we for SOC 2?”, “What is overdue and who owns it?”, “What does the auditor need for CC6.1?”. The assistant speaks the open Model Context Protocol (MCP), so any MCP client can connect.
1. What it is
- The assistant acts as the person who connected it, with that person’s role. It sees what they see in Proofroom and nothing more.
- Proofroom never receives your data or your AI keys. Your stack answers the assistant’s questions and calls no AI service itself. What the assistant reads goes to the AI service your client uses, as with anything else you paste into it.
- MCP is off until an administrator turns it on. Nothing about it is sent to us.
2. Turning it on
Admin → AI assistants (needs the settings permission).
| Setting | Meaning |
|---|---|
| Let AI assistants connect (the On checkbox) | The switch. Off by default. Assistants act as the person who connects them: they can read what that person can read, and re-run integration checks if their role allows it. When on, the page shows the address to give your clients. |
| Which assistants: Only clients added by an administrator | The default. Only the clients you add (section 3) can connect. People need the client ID you give them. |
| Which assistants: Any MCP client: each person approves it when connecting | Each person approves the client when connecting. Clients identify themselves by a web address or register themselves, and the consent page marks their name as unverified. |
The address of your MCP server is:
https://<your Proofroom>/api/mcp
Switching to “only clients added by an administrator” disconnects every client that is not on your list. Turning MCP off disconnects every client.
While MCP is off, the MCP address and its sign-in addresses answer 404 with one sentence, which clients show: “AI
assistants are turned off on this Proofroom. An administrator can turn them on in Admin → AI assistants.”
3. Adding a client
Admin → AI assistants → Clients. Add each AI client your people may use; in approved-only mode, only clients on this list can connect. First choose the kind of client:
- Runs on people’s computers (a desktop app, an editor, a terminal tool). The redirect addresses are filled in,
one per line:
http://localhost/callbackandhttp://127.0.0.1/callback, since a client may return to either name. Any port matches, since these clients pick one when they start. Change the path only if the client’s guide gives another. The client is public: it proves itself with PKCE and has no secret. - Runs in the vendor’s cloud. Paste the redirect address from the vendor’s setup page. A secret is optional; ask for one if the vendor’s setup page has a field for it.
Then give it a name, which people see on the consent page.
After you add it, the page shows what to give people, each with a Copy button:
- the MCP address,
https://<your Proofroom>/api/mcp; - the client ID (starts
pmc_); - the client secret, if you asked for one. It is shown once.
The list shows each client’s name, kind, client ID, active connections, and Disable and Delete. The kind is worked
out from the redirect addresses: all on localhost (or 127.0.0.1, [::1]), with no secret, means people’s
computers. A client in the vendor’s cloud cannot have only localhost addresses: the vendor’s service cannot reach a
person’s own computer, so Add client refuses it and asks for the vendor’s address.
A client you configure by hand needs these values:
| Field | Value |
|---|---|
| Client ID | shown after you add the client (starts pmc_) |
| Client secret | shown once, if you asked for one |
| Authorization URL | https://<your Proofroom>/oauth/authorize |
| Token URL | https://<your Proofroom>/api/oauth/token |
| Scope | proofroom |
| Resource (audience) | https://<your Proofroom>/api/mcp |
| PKCE | S256, required |
Most clients need only the MCP address and the client ID, and find the rest themselves.
In “any client” mode you do not need to add clients, and people need no client ID: clients register themselves or identify themselves by a web address. Adding one still gives it a name people can trust on the consent page.
4. Connecting
- In the AI client, add an MCP server with the address
https://<your Proofroom>/api/mcpand, in approved-only mode, the client ID from your administrator. - The client opens your browser at Proofroom. Sign in as you normally do (single sign-on, or password and authenticator).
- Read the consent page: the client’s name, where it will return to, and that it acts as you with your role. Choose Allow.
Many terminal clients take the address and a client ID on one line:
<client> mcp add --transport http --client-id <client ID> proofroom https://<your Proofroom>/api/mcp
The client then opens your browser for sign-in the first time you use it. Without a client ID, a client on an approved-only Proofroom tries to register itself and is told that an administrator adds AI clients.
If the consent page was left open long enough for your session to time out (8 hours idle), Allow sends you to sign in again and then back to the same consent page. Emergency accounts cannot connect AI assistants.
The consent page is shown every time a client connects; an earlier approval is not remembered. Access lasts one hour and is renewed in the background for up to 30 days of use; after that, or after any revocation, the client sends you back to step 2.
5. Tools
Results include a link to the page in Proofroom for what they return. Lists hold at most 50 items and come with a cursor for the next page. Something your role cannot do is answered “Your role (Analyst) cannot do this in Proofroom.” (with your role). An item that does not exist, or that you cannot see (an audit you are scoped away from, an archived audit, another person’s private evidence), is answered “Not found.”, the same in both cases.
| Tool | Returns | Needs |
|---|---|---|
list_audits |
Audits you can see: name, framework, period, status, readiness | view audits (per audit) |
audit_readiness |
Readiness, control counts by status, and the controls with no current evidence (status gap or not started) | view the audit |
list_controls |
Controls of an audit with owners, status, evidence count and newest evidence date; filter by status, owner role (ownerRoleId, from each control’s ownerRoleIds), category or missing evidence |
view the audit |
get_control |
Requirement text, mapped controls in other frameworks, linked evidence with review state, the last 20 comments | view the audit |
my_work |
Your overdue and due workflow checks, your rejected submissions, and items waiting for your review. Reviewers (admin, auditor) also get the first 20 evidence items waiting in the review queue | as the dashboard |
list_workflow_checks |
Workflow checks with area, owner, period, due date, state and frameworks, for the tabs open to you; filter by status or owner | as the Workflow page |
list_integrations |
Integrations and their collectors: enabled, schedule, last run and its status or error | view integrations |
get_run |
One run: status, timings, error, and the evidence collected from the integration while the run ran, with the start of each item’s text (the first 4,000 characters, returned only to roles with evidence download; other roles get none) | view integrations |
rerun_collection |
Queues a new run of one collector (the only write), then you read the result with list_integrations or get_run |
manage integrations |
search_evidence |
Evidence by text, audit, control, dates, review state or source | as the Evidence page |
list_policies |
Policies, procedures and standards: kind, owner, approved version, effective and next review dates and review state; editors also see open drafts | as the Policies page |
get_policy |
One document: the approved version’s fields and text (fields filled in) in pages of 20,000 characters, and the versions you may see | as the Policies page |
get_evidence |
One evidence item: details and description, linked controls, review state and its extracted text in pages of 20,000 characters. Each link carries secondOpinion whenever the evidence check has recorded a verdict for it, also after the check is turned off (label, probabilities, coverage, reason, model, when, stale), read-only: a second opinion, people decide. Files are not sent; the link opens them in Proofroom. |
as the Evidence page; text also needs download permission; secondOpinion for analysts, auditors and admins |
Text from evidence, comments, integration results and documents comes from outside Proofroom. The tools mark it as data, not instructions.
Controls are owned by roles (People → Roles). Each control lists its owners (the role’s owner person, or the role’s
name when it has none) and their ownerRoleIds; pass one of those as ownerRoleId to list the controls a role owns.
When the licence has expired and Proofroom is read-only, the read tools keep working and rerun_collection is
refused with the read-only message. Disconnecting still works (section 8).
6. Where it must be reachable from
| The client runs | Your Proofroom must be reachable |
|---|---|
| On the person’s computer: a desktop app, an editor, a terminal tool | From that computer. A Proofroom that only your office network or VPN can reach works. |
| In a vendor’s cloud | From the internet, or through a gateway you run for it. |
In “any client” mode, clients that identify themselves by a web address are looked up by your Proofroom, which needs outbound HTTPS to fetch the client’s description.
7. Limits
| Where | Limit |
|---|---|
| Registering a client (any-client mode) | 10 per IP per hour |
| Looking up a client’s web address | 20 per IP per hour |
| Token requests | 30 per IP per minute |
| MCP calls | 120 per connection per minute; a batch of requests counts each request |
rerun_collection |
5 per collector per hour |
The limits are kept in memory per process. Registering, token requests and MCP calls answer 429 with a
Retry-After header. Looking up a client’s web address happens on the consent page, which shows “Too many requests:
try again later.” instead. rerun_collection over its limit returns a tool error (the collector was re-run 5 times in the last hour), not
429.
8. Revoking
- A person opens Profile → Connected apps and chooses Revoke next to a client.
- An administrator opens Admin → AI assistants → Connections and revokes one connection or all of them. Deleting or disabling a client, disabling a user, resetting a user’s authenticator, and turning MCP off also end connections.
- Changing your password, or setting a new one through a reset link, also ends all your connections, as it signs out your other sessions.
- To keep out a client that registered itself or identifies itself by a web address, disable it. Deleting it ends its connections, but the client can register or be looked up again on its next attempt.
- A revoked connection stops working on its next call.
- These still work while an expired licence makes Proofroom read-only: turning MCP off, revoking connections (yours or, for an administrator, one or all), and disabling or deleting a client. Turning MCP on, allowing any client, and adding or enabling a client wait for a valid licence.
Only connections that can still be used are listed. A consent that was never finished, or a connection whose 30 days ran out, drops off the list, and the daily housekeeping revokes it (reason “expired” in the audit log).
If a refresh token is used twice, which means a copy leaked, the whole connection is revoked.
9. The audit log
The audit log records turning MCP on or off and changing the client mode; adding, changing and deleting clients; a person allowing a client; every revocation with its reason; and refresh-token reuse. The one write, a re-run, appears as the normal integration event and names the client that made it. Reads are not logged one by one, as the app does not log page views; each connection shows when it was last used.
Connections and clients are part of a stack’s backups. Exports leave them out, and the MCP setting too, so an import never carries access across: the imported stack starts with MCP off.