MCP Integration
Permissions
Control exactly what each API key or OAuth client can see and do — from entire workspaces down to individual folders.
Permission Model
Every MCP credential (API key or OAuth client) is scoped to specific resources within your organization. Access is controlled at two layers:
- Resource scoping — which workspaces, projects, and folders the credential can access.
- Operation permissions — what the credential can do with those resources (read, write, delete).
Resource Hierarchy
Stable Baseline organizes content in a three-level hierarchy. Each credential must be scoped to at least one workspace, and can optionally be narrowed further:
Workspace
Top-level container. Selecting a workspace grants access to all projects and folders within it (unless further scoped).
Project
A collection of documents and folders under a workspace. Selecting specific projects limits access to only those projects.
Folder
Folders within a project. The most fine-grained level of scoping — restrict access to specific document folders only.
Simple vs Granular Permissions
Simple Mode (Default)
In simple mode, you select a set of operations that apply uniformly to all scoped resources:
| Permission | Allows |
|---|---|
| read | List and read organizations, workspaces, projects, folders, documents, diagrams, and images. |
| write | Create and edit documents, folders, diagrams, and images. Includes read access. |
| delete | Delete documents, folders (recursively), diagrams, and images. Includes read and write. |
Granular Mode
Enable granular permissions to set different read/write/delete permissions on each individual resource. For example, you might grant:
- • Workspace A — read only
- • Project X (within Workspace A) — read + write
- • Folder "Specs" (within Project X) — read + write + delete
This is useful when you want an agent to have broad visibility across your workspace for context but only write to a specific project, or when multiple teams share a workspace and you need to restrict editing to certain areas.
Permission Inheritance
Permissions follow the resource hierarchy. When using granular mode:
- A project can only have permissions that its parent workspace allows.
- A folder can only have permissions that its parent project allows.
- Write permission at a child level requires at least write at the parent level.
- Delete permission at a child level requires at least delete at the parent level.
The settings UI enforces these constraints automatically — you won't be able to enable write on a project if its workspace is set to read-only.
Best Practices
Principle of Least Privilege
Grant only the permissions each credential actually needs. Use project- or folder-level scoping rather than giving blanket workspace access.
Use Short Expirations for CI/CD
For automated pipelines, use 30- or 90-day keys. Rotate them before they expire. The dashboard shows last-used timestamps to help you track usage.
Separate Keys per Use Case
Create one key per client or integration. This makes revoking straightforward if a key is compromised, without disrupting other integrations.
Prefer OAuth for Third-Party Apps
If you are building an integration that other users will connect to, use OAuth 2.1. This provides a proper consent flow and avoids sharing long-lived secrets.
Review Active Keys Regularly
Check the "Last Used" timestamp on each key. Revoke any keys that haven't been used in a long time or belong to decommissioned integrations.