Permissions & Isolation

The Talkable MCP server enforces the same permission model as the dashboard: an agent can do over MCP exactly what your role can do in the Talkable admin — no more, no less. Two independent checks apply to every call:

1. Scope — the credential must carry the right scope (mcp:read for reads, mcp:write for writes). See authentication & scopes.

2. Role — the acting user must have the required role on the specific site the call names.

What each role can do

Your Talkable role on a site determines which tools you can use for it. Account admins have full access to their account’s sites.

Role	Reporting reads (campaigns, metrics, reports)	Support lookups (referral / person / coupon)	Support actions (approve, void, unsubscribe, anonymize, expire)
Admin	✓	✓	✓
Write	✓	✓	✓
CSP	—	✓	✓
Read	✓	✓	—

If a call exceeds your role, the tool returns a clear “access denied” message naming the permission required, and tools you can never use for any of your sites are not offered in the tool list at all.

Note

The role table above describes personal keys and OAuth, which act as a specific user. A scoped account or site key (created under Account settings → API Keys & MCP) is instead authorized by the key itself — its scopes and the sites it covers — so its reach is fixed by the key rather than by any one person’s per-site role.

Available tools

The tools a customer agent can use are listed below. The Role column is the site role required to call the tool (+ means that role or higher). Write+ or CSP tools are the customer-support write actions — available to write-or-above users and to the customer-support (CSP) role — while Read+ or CSP lookups are available to read-or-above users and the CSP role. Every write tool additionally requires the mcp:write scope on the credential (see authentication & scopes).

Two helper tools are always present: list_sites (discover the sites and site_slug values you can use) and prompt_ai_assistant (hand a natural-language task to the Talkable AI Assistant, which runs with your permissions).

Tool	Role	Description
calculate_metric	Read+	Calculate a metric with filters and segmentations.
check_site_integration	Read+	Verify the site’s Talkable JS integration is live.
get_account_settings	Read+	Get account-level settings.
get_campaign	Read+	Get details of a campaign.
get_coupon	Read+ or CSP	Look up a coupon by code, or by ID (Read+ only).
get_grid_export	Read+	Get the status/result of a grid (CSV) export.
get_person	Read+ or CSP	Look up a person by email, or by ID (Read+ only).
get_referral	Read+ or CSP	Look up a referral by ID.
get_site_settings	Read+	Get site settings, optionally by category.
list_campaigns	Read+	List campaigns for a site.
list_coupon_lists	Read+	List the site’s coupon lists with code counts.
list_grid_reports	Read+	List available grid report types and filters.
list_incentives	Read+	List a campaign’s incentives.
list_locale_entries	Read+	List a campaign’s locale entries (copy/config).
list_metrics	Read+	List available metrics.
list_placements	Read+	List the site’s placements.
list_settings_changes	Read+	List recent setting changes for a site.
list_split_tests	Read+	List A/B tests for a site.
list_traffic_sources	Read+	List the site’s traffic sources.
list_view_setups	Read+	List a campaign’s view templates.
schedule_grid_export	Write+	Schedule a CSV export of a grid report.
search_product_docs	Read+	Search Talkable product documentation.
skill_search	Read+	Search saved assistant skills.
update_coupon	Write+ or CSP	Expire a coupon (stops future redemptions).
update_person	Write+ or CSP	Unsubscribe, resubscribe, or anonymize a person.
update_referral	Write+ or CSP	Approve or void a referral.

Warning

Two support actions have real-world effects worth confirming before you ask an agent to run them:

• Anonymizing a person (update_person with anonymize) permanently erases the person’s identifying data. It cannot be undone.

• Approving a referral (update_referral with approve) releases real rewards — coupon codes or loyalty points are issued to the customer shortly after approval, along with reward emails and webhooks.

Both actions execute only when the call includes confirm: true — without it, the tool returns a preview of what would happen instead of executing. Both tools also support dry_run: true for an explicit no-side-effects preview.

Tenant isolation

Every MCP credential is bound to a single Talkable account, and every tool call is scoped to one site:

• list_sites returns only the sites in your account that you can access.

• Each tool call takes a site_slug. Talkable resolves it only within the sites you can access — a slug from another account (or an unknown slug) is rejected with “Site not found or not accessible.”

• A credential can never read or change another account’s data.

Revoking access

You can revoke an agent’s access at any time:

• Personal API keys — My Profile → API Keys, then Revoke next to the key. The key stops working immediately.

• Scoped account & site keys — Account settings → API Keys & MCP, then Revoke next to the key (admins only).

• OAuth-connected agents — My Profile → Connected Apps, then revoke the client.

• Deactivating a user revokes all of that user’s MCP credentials.