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. Access is tied to each user’s role in Coverbase. Admins and Members get read and write. Guests and Siloed Members are read-only. 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.
RoleCan connect to MCP?Read toolsWrite tools
AdminYesYesYes
MemberYesYesYes
Siloed MemberYesYesNo (read-only)
GuestYesYesNo (read-only)
Auxiliary MemberNo——
Service AccountNo——
A few things worth calling out:
  • 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 and Service Accounts cannot use the MCP server at all. These are non-interactive identities, so they are excluded from the connectable set entirely and receive a 403 if a token for one is ever presented.
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 — and 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), 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 access token must carry the mcp:write scope. Tokens can be issued without it to produce a strictly read-only connection, even for a user whose role would otherwise allow writes. (See OAuth 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.

​
OAuth scopes

The server defines two scopes:
ScopeGrants
mcp:readAccess to all read tools (search, detail, reports).
mcp:writeAccess to write tools, in combination with a Member/Admin role and explicit confirmation.
By default, tokens are issued with both scopes, so in normal use the user’s role is the effective read-only-versus-read/write switch. The authorization endpoint also accepts a narrower scope request, which makes it possible to mint a deliberately read-only token even for a user who could otherwise write.
Want a guaranteed read-only connection? Two levers give you that:
  1. Connect with a Guest or Siloed Member account — their role blocks writes regardless of scope.
  2. Or issue a token without the mcp:write scope — writes are blocked regardless of role.
Either is sufficient on its own; the write guard requires both a write-capable role and the write 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.
  • 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 OAuth user 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.

Security and privacy

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