MCP permissions

The MCP server needs no permission of its own: any valid API token or OAuth connection can reach it. Each tool then checks what it needs, and tools/list shows only the tools your connection could use. A tool missing from the list almost always means a permission is missing.

Checks run in this order, on every call:

1. Connection type: read-only, actor-limited, run token.
2. Token permissions, on permission-limited tokens.
3. Organization role, when you act for an organization.
4. Listening project role, on listening tools that touch a project.

Read-only connections

A read-only API token, or an OAuth connection where you ticked Read-only, gets every reading tool and none of the tools that start runs or change data:

Hidden on read-only
Actors and runs	call-actor, abort-run, per-actor tools
Social listening	label-mentions, save-audience-estimate, and every API tool that writes (create-…, update-…, delete-…, set-project-status, collect-project-now, add-source, bulk-sources, import-posts, track-creator, untrack-creator, verify-mentions)

Token permissions

Full-access tokens and OAuth connections have every permission. A permission-limited token sees a tool only if it has the tool's permission:

Permission	Tools
actors.read	search-actors, get-actor-details
actors.run	call-actor, per-actor tools
runs.read	get-run, list-runs, get-run-log; also get-dataset-items and get-key-value-record when called with run_id
runs.write	abort-run
storages.read	get-dataset-items, get-key-value-record
listening.read	list-listening-projects, search-mentions, list-attributes, list-authors, get-audience, and every listening API tool that reads
listening.write	label-mentions, save-audience-estimate, and every listening API tool that writes

So a token with only listening.read works for an AI that reads listening data, and sees no actor tools at all.

Actor-limited tokens

A token limited to some actors:

• sees only those actors in search-actors, get-actor-details, call-actor and per-actor tools;
• sees only runs of those actors in list-runs, get-run, get-run-log and abort-run;
• reads only the default dataset and key-value store of those runs;
• gets no social listening tools.

Run tokens

The token an actor gets while it runs can't use the MCP server's tools.

Organization roles

When you act for an organization, your role there applies on top of the token. Owners and admins have every permission; members and custom roles have what their role grants.

Role permission	Needed for
Start runs	call-actor, per-actor tools
Manage runs	abort-run
View social listening	Every listening tool
Manage social listening	create-listening-project
Verify mentions	The verify queue on projects where your project role doesn't already give it

A tool your role doesn't allow is hidden from the list, or answers "Your role in this organization does not allow this (…)". See Roles and permissions.

Listening project roles

Inside a project, your project role decides, exactly as in the Console. It's checked on each call, so a tool can be listed and still refuse on a project where your role is lower.

Role	Tools that work
viewer	Every reading tool
analyst	Also label-mentions, update-mention, save-audience-estimate, delete-audience-estimate, update-lead, the verify queue
manager	Also project settings and status, sources, collect now, import posts, attributes, creators tracking, campaigns, alerts, reports

Owners, admins and personal accounts are managers of every project of the account. Have the AI call get-my-project-access before it changes anything: it returns your role and what it can do.

Recommended setups

Goal	Connect with
An assistant that only looks	OAuth with Read-only ticked, or a read-only token
Listening analysis that labels mentions	Token with listening.read and listening.write, analyst role on the project
One scraper, nothing else	Token limited to that actor, with ?actors= for its own tool
Full automation	OAuth or a full-access token, with a spending limit on the account

Related

• Tool reference
• Authentication
• Troubleshooting