Tools and permissions reference
The scopes a Suede MCP connection can request, what tools it exposes, and how access is enforced.
This page covers what an MCP connection can access and how Suede enforces it. You don't need any of it to connect — assistants negotiate scopes and discover tools on their own — but it's useful when you're deciding what to grant or auditing a connection.
Scopes
A scope is a category of access. Sign-in connections request scopes during approval; static credentials are assigned scopes when you generate them. Grant the least a connection needs.
| Scope | Grants | Roles that can exercise it |
|---|---|---|
data:read | Read AI visibility, citations, competitors, topics, personas, and prompts. | All roles, including Viewer |
data:write | Create and update topics, personas, prompts, and owned domains. | Owner, Admin, Member |
org:write | Create pitch spaces and workspaces, and manage organization-level resources. | Owner, Admin |
A connection can hold a scope but still be blocked by your role — both must allow the action. A Member with a data:write credential can edit monitoring data, but the same credential held by a Viewer stays read-only. See Roles.
Sign-in connections also request the standard OpenID scopes (openid, profile, email, offline_access) so the assistant can identify you and refresh its session. These don't grant access to your monitoring data.
Tools
The assistant discovers the current tool list automatically once connected, so you never configure tools by hand. At a high level:
Read tools (data:read)
- AI visibility and competitors — your citation share and how it's changing, competing domains and social accounts.
- Citations and sources — citations grouped by source category, and drill-downs on individual domains and sources.
- Responses — recent AI responses that mention you, full-text search across them, and single-response detail.
- Entities — detail on topics, personas, prompts, and peers.
- Account and setup — list the workspaces you belong to, available filters, monitored AI platforms, and a health check.
Write tools
- Monitoring data (
data:write) — add, update, and remove topics, personas, persona categories, prompts, owned domains, and owned social accounts. - Competitors (
data:write) — manage peers, peer sets, and their domains and social accounts. - Organization profile (
data:write) — update workspace name and logo. - Workspaces and pitch spaces (
org:write) — create child workspaces and pitch spaces.
How access is enforced
Every call is checked in order, and the first failing check stops it:
- Identity — the access token must be valid and issued for the Suede MCP server.
- Scope — the connection's granted scopes must include the one the tool needs.
- Workspace — the call resolves to a workspace you're a member of; you can't reach data in workspaces you don't belong to.
- Role — write tools additionally require the matching permission for your role.
- Plan and rate limits — the workspace's plan must allow the action, within its usage and rate limits.
This is the same permission model as the dashboard: a connection can never do something your account couldn't do in the UI.
Authentication details
Sign-in connections use OAuth 2.1 with PKCE, and tokens are bound to the Suede MCP server (RFC 8707 audience binding). Compliant clients handle the discovery, sign-in, and token refresh automatically — there's nothing to configure beyond pasting the server URL. Static credentials use the OAuth client-credentials pattern with the client ID and secret you generate; see Static credentials.
Usage and billing
MCP calls count toward your workspace's usage. The Free plan includes 100 read-only calls per month; paid plans meter calls as you use them. See Plans and Usage and overages.