Skip to main content
For AI agents: a documentation index is available at https://docs.coverbase.com/llms.txt. This page is also available in markdown by appending .md to the URL.
The Coverbase MCP server does not have its own permission system. Every tool call runs as the person who authorized the connection, with exactly the access that user already has in Coverbase, no more. There are no separate MCP credentials, no service identity that sees more than the user, and no way for the assistant to escalate beyond what the user could do in the dashboard. This page explains how that works end to end: how a request is authenticated, how a role is resolved, and how read-only versus read/write access is decided and enforced.
The short version. Two things decide access: the role of the identity connecting, and the scopes on the credential. Admins and Members can write; Guests and Siloed Members are read-only. On top of that, an API key can be minted read-only, which withholds write regardless of role. Change someone’s role in Coverbase and it takes effect on their next request; there is nothing separate to re-issue.

​
Permission inheritance

When a client connects, the user signs in to Coverbase through OAuth 2.0 and authorizes the connection. From that point on, every tool the assistant calls is evaluated against that user’s live organization membership. The connector is a delegate, not a privileged service account. Three properties follow from this design:

No privilege escalation

The assistant can never see or do more than the connected user could do by logging into the dashboard themselves.

Single source of truth

Permissions are read from the user’s organization membership, not from a static config baked into the connector or copied at install time.

Org isolation

Every call is scoped to the user’s organization. The client never supplies an organization ID; the server derives it from the authenticated session.

​
Role-to-access matrix

Coverbase organization roles map to MCP access as follows. A few specifics:
  • Read access (search vendors, pull assessment detail, list findings, run portfolio reports, and so on) is available to every role that can connect.
  • Write access (creating or updating vendors, assessments, findings, obligations, notes, tags, and other records) is reserved for Members and Admins.
  • Auxiliary Members cannot use the MCP server at all, and receive a 403 if a token for one is ever presented.
  • Service Accounts are non-interactive by design, so they cannot sign in through OAuth or a dashboard session; those paths still return 403. They can hold an API key, which is what makes a programmatic read-only connection possible without a human seat. A service account can never write through MCP.
The MCP write boundary is deliberately conservative. Write access through the connector is limited to Members and Admins, so it is never broader than what the same user could do in the dashboard. For some roles it is intentionally tighter. If you need a user to make changes through an assistant, give them the Member or Admin role.

​
How a request is authorized

Every request flows through the same gate, regardless of which client or token type it uses. There is no path that skips role resolution.
1

Authenticate the token

The server accepts three token formats on the Authorization: Bearer header: an OAuth 2.0 access token issued to a remote MCP client, a dashboard SSO session token, or a long-lived Coverbase-issued MCP API key. Anything else is rejected with 401.
2

Resolve the live role

The user’s organization role is resolved from their current membership record, not from anything cached in the client. For API-key and session tokens, the membership is looked up on every request. For OAuth tokens, the role is bound to the token from live membership at authorization time and re-validated every time the token is refreshed (see Live revalidation).
3

Enforce the connect allowlist

If the resolved role is not one of the connectable roles (Guest, Siloed Member, Member, Admin, plus Service Account on an API key), the request is rejected with 403 before any tool runs.
4

Enforce per-tool access

Read tools proceed for any connectable role. Write tools pass through an additional guard described in Write protection before they touch any data.
5

Scope to the organization

The organization is taken from the authenticated session and applied to every query automatically. The client cannot widen the scope by passing a different organization ID; there is no parameter to do so.

​
Write protection

Read-only versus read/write is not a single switch: a write tool only executes when three independent conditions are all satisfied. Any one of them failing returns a clear, non-destructive error instead of performing the change.
1

Role check (least privilege)

The connected user’s role must be Member or Admin. Guests and Siloed Members receive a message explaining that their role cannot run write tools, and are pointed to ask a Member or Admin.
2

Scope check

The credential must carry the mcp:write scope. An API key minted read-only, or an OAuth token issued without it, produces a strictly read-only connection even for a user whose role would otherwise allow writes. (See Scopes.)
3

Explicit confirmation (human-in-the-loop)

Every write tool requires an explicit confirm=true argument. Without it, the tool returns a precondition error rather than executing, so the assistant is forced to surface the proposed change to you and wait for your approval before anything is written.
These checks are applied server-side, inside the write guard, before any database write. They do not rely on the client or the model behaving correctly. A misbehaving or compromised client cannot bypass the role check, the scope check, or the confirmation requirement.

​
Scopes

The server defines two scopes: Every credential carries mcp:read. Whether it also carries mcp:write is fixed when the credential is issued:
  • API keys store their scopes on the key itself. Tick Read-only when you generate one under Configuration → MCP Server and the key never carries mcp:write, not now and not if the owner is promoted to Admin later. The key list shows the grant on each key.
  • OAuth tokens are issued with both scopes by default. The authorization endpoint also accepts a narrower scope request, so a client can ask for mcp:read alone.
A read-only credential is not merely refused at the last moment. The mutate tool is hidden from such a connection: it does not appear in the client’s tool list, and mcp_capabilities reports no mutations. The assistant never proposes a change it cannot make, so you are never asked to confirm a write that was going to fail.

​
Programmatic read-only access

The common case is a pipeline, a scheduled report, or an internal assistant that should read Coverbase and never change it. You do not need a human seat for this.
1

Generate the key as an admin

Go to Configuration → MCP Server and choose New API key.
2

Choose what the key acts as

Service account is the usual answer: a built-in non-human identity that needs no seat in your identity provider and never signs in. Choose Another user instead to attribute the key’s activity to a particular member, such as a Guest kept for reporting.Either choice makes the key read-only automatically. A key that authenticates as someone else can never write, so a change is never recorded under a name that did not make it.
3

Store the key

The secret is shown once. Send it as Authorization: Bearer cb_mcp_... from your client. See Connecting clients.
You keep control of a key you minted for a service identity: it appears in your key list and you can revoke it, even though it authenticates as something else. For what shows up in the audit trail once it is running, see Attributing a key that acts as a service account.
Want a guaranteed read-only connection? Any one of these is sufficient on its own, because the write guard requires both a write-capable role and the write scope:
  1. Mint the API key read-only.
  2. Bind the key to a service account or another user, which forces read-only.
  3. Connect with a Guest or Siloed Member account; their role blocks writes regardless of scope.

​
Live revalidation

Because permissions are resolved from live membership, changes you make in Coverbase propagate without any re-install or token re-issuance on the user’s side.
  • API-key and session tokens look up the user’s membership on every request. If the user has been removed from the organization, the request is rejected with 403, even if the token itself is still otherwise valid. A key’s scopes do not follow the role: a read-only key stays read-only through any promotion, which is what makes it safe to hand to an automation.
  • OAuth tokens bind the role at authorization time and re-check live membership on every refresh. A user who is demoted (for example, Member → Guest) or removed from the organization cannot keep using a previously elevated token: the next refresh either downgrades the role baked into the new token or fails outright. Access tokens are short-lived and clients refresh silently, so a role change converges quickly.
This means a demotion is also a downgrade of MCP access, and a removal is a revocation, without anyone needing to touch the connector. Revoking the connection from Coverbase account settings or the client invalidates the token immediately.

​
What this means in practice

The assistant can search vendors, pull the vendor’s full profile, list findings and assessments, and run reports; all read operations succeed. The update is blocked by the role check and the assistant is told the user’s role cannot perform writes. No data is changed.
The role check passes (Member is write-capable) and the default token carries mcp:write. The assistant proposes the new finding and waits. Once you confirm, it re-runs the tool with confirm=true and the finding is created, and the action is recorded in the audit trail.
On the user’s next request (API key/session) or next token refresh (OAuth), the new Guest role takes effect. Subsequent write attempts are rejected. There is nothing to reconfigure on the user’s machine.
The next request or refresh fails with a 403 because there is no active membership to resolve a role from. The connection effectively stops working immediately.

​
Auditability

Every tool call, read or write, is logged with the connected identity, the tool name, the parameters, a timestamp, and the outcome. Write actions taken through the MCP server land in the same Coverbase audit trail as actions taken in the dashboard, so administrators have one consolidated record of who did what, regardless of whether it happened through the UI or an assistant.

​
Attributing a key that acts as a service account

A reasonable question about any non-human credential: if it changes something, whose name is on it? For MCP keys the answer is that it cannot change anything. A key bound to a service account or to another user is read-only, and a service account is additionally excluded from the write-capable roles. A bound key never produces a write in your audit trail, so there is no such thing as a change you cannot trace to a person. Only a key that acts as you can write, and those entries carry your name exactly as if you had made the change in the dashboard. What you can still see for a bound key:

Who provisioned it

Creating and revoking an MCP key are recorded in Settings → Audit log under Integrations, attributed to the admin who did it, with the key’s name. The key also stores that admin internally, so a key always traces back to a person even though it runs unattended.

What it read, and when

Every tool call the key makes is logged with the connected identity, the tool, the arguments, and the outcome. Read activity is recorded, not just writes.
One service account identity is shared by every integration in your organization, and it is the same identity behind your REST API keys. Two MCP keys bound to it are not distinguishable from each other in the per-call logs, which record the identity rather than the individual key.So issue one key per integration rather than reusing a single key across several, and give each a name that says what it is for. That way the provisioning record in the audit log tells you which integration was set up when and by whom, and revoking one key stops exactly one integration instead of all of them at once.
This differs from the REST API, where each request records the calling ak_ key’s id and name alongside the shared identity. Per-key attribution on individual MCP tool calls is not available today.
If you need machine activity attributed to a distinct named identity rather than the shared service account, bind the key to a dedicated user instead: create a Guest for it and use Another user when generating the key. That costs a seat in your identity provider, which the service account option avoids, so it is a trade between attribution granularity and provisioning overhead.

Security and privacy

Authentication, transport security, what we log, what we don’t retain, and how to revoke access.