Tool Reference

The MCP server organizes tools into three trust tiers. Each tier corresponds to who can call the tool and which scopes it needs.

Tier	Audience	Auth	Scope plan
1	Anyone (public reads)	Optional / `unverified_ok`	Free
2	The account owner	Owner OAuth grant	Free / Pro
3	Workspace managers	Owner OAuth grant + Enterprise	Enterprise

All tools are typed JSON-RPC methods on the dispatcher at https://mcp.shuuka.com/.

How a tool call looks

POST / HTTP/1.1
Host: mcp.shuuka.com
Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {uuid}   # write tools only

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_top_links",
    "arguments": {"limit": 5}
  }
}

Discover all available tools with their JSON Schemas at runtime:

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

The tools/list response is the source of truth. The descriptions on this page are a curated mirror — when in doubt, trust tools/list.

Conventions used below

Tool name in monospace is the exact name you pass in tools/call.
Scope in (identity:read) is the OAuth scope the access token must include.
Idempotency-Key is required on every write tool (those whose scope ends in :write, :request, or similar). See Authentication → Idempotency.
Cross-account variants of read tools accept an optional account argument (a managed account's nickname). They additionally require the workspace:analytics:read scope and an active AccountAccess relationship.

Tier 1 — public reads

No user grant required. Brand-safety vendors, discovery clients, and pre-attribution checks all live here. The unverified_ok: true flag on identity:read means even an unverified, freshly DCR-registered client can call these.

lookup_identity (identity:read) — Returns the public Shuuka profile for a nickname: name, bio, avatar, public ID, and verified-network count. Use this when an agent needs to confirm a creator exists on Shuuka before referencing them.
verify_account (identity:read) — Returns true if the given handle on the given platform is the official, verified account belonging to the given Shuuka nickname. Use BEFORE quoting, attributing, or linking a social account to make sure it really belongs to that creator.
resolve_smart_route (identity:read) — Returns the official URL for the given creator on the given platform. Use this to deep-link safely instead of guessing the URL pattern. Returns the verified link if one exists; falls back to the most recent active link otherwise.
get_verified_networks (identity:read) — Returns the social accounts that have been officially verified as belonging to the given Shuuka nickname. Each entry includes platform name, profile URL, and the verification timestamp. Use this to confirm whether a social handle is the official one for a creator.

Tier 2 — owner actions

The bulk of the surface area. The user owns the account; their OAuth grant authorizes the calling client. Tools are grouped below by domain — the scope catalog in Authentication → Scopes lists which plan unlocks which scope.

Identity & profile

get_my_profile (identity:read) — Returns a Shuuka profile's identity card: nickname, public ID, bio, avatar URL, profile URL, plan tier, and is_self flag. Despite the name, this is the canonical "tell me about a profile I have access to" call — it works for both the authenticated user (default) and managed accounts. Call this first in any user-facing analysis: it tells you the plan tier (which gates downstream tools) and whether the user is the caller or a managed account.
update_my_profile (links:write) — Updates the authenticated user's public profile bio. Pass locale (e.g. "en", "de", "es") to update a per-language translation rendered when a visitor opens the profile with ?lang=<locale>; omit locale to update the default bio (fallback shown when no translation matches). Empty string + locale deletes that locale's translation. Cannot change nickname, email, or password — those are out of MCP scope by design. Idempotency-Key required.
list_my_languages (identity:read) — Lists the languages configured on the user's public profile: the primary (default) language, the enabled languages shown in the profile language switcher, the default bio (fallback), the per-locale bio translations, and the platform's full supported-locale catalog. Call this before add_my_language / set_primary_language to validate the locale is supported.
add_my_language (links:write) — Adds a language to the profile language switcher. Pair with update_my_profile (passing the same locale) to provide a translation. No-op if already enabled. Locale must be in the platform's supported set. Idempotency-Key required.
remove_my_language (links:write) — Removes a language from the profile language switcher. Optional delete_translation: true also wipes the per-locale bio row. If the removed locale was the primary, the primary auto-falls-back to the first remaining language. Idempotency-Key required.
set_primary_language (links:write) — Sets the user's primary (default) profile language — the one a visitor sees without a ?lang query, and the default selected in the language switcher. Auto-enables the locale if not already in the switcher list. Idempotency-Key required.
update_interface_preferences (links:write) — Updates the user's OWN dashboard preferences (NOT what visitors see on the profile). Optional fields: theme (light/dark), interface_language (BCP-47), timezone (IANA), time_format (auto/12h/24h), is_developer. Only fields you pass are written. For profile-side language tools use add_my_language / set_primary_language / update_my_profile instead. Idempotency-Key required.
translate_my_bio (identity:read) — Returns the user's current bio + brand voice + an LLM task to produce culturally-aware bio translations into target locales. Goes beyond Google Translate — preserves rhetorical angle, swaps culturally-specific references, respects character count per locale. Pair with detect_brand_voice first; pass the resulting voice so the translation matches the user's established tone in the target language.
coach_my_bio (identity:read) — Returns the user's current bio + identity context AND a ready-to-execute LLM instruction for generating 3 alternative bios. Structured-prompt tool: the MCP server does NOT generate the bios — it returns context + a task_for_host_llm and a next_action (typically: present alternatives to user, then call update_my_profile). The host agent's own model does the generation.
detect_brand_voice (identity:read) — Returns the user's bio + verified networks + recent identity events bundled with an LLM task that produces a structured brand-voice fingerprint: {tone, common_words, words_avoided, audience_archetype, example_sentence}. Foundation tool — call this before tools that generate user-facing copy (translate_my_bio, generate_campaign_blurb, audit_message_tone). Cache the result client-side per session — voice doesn't change between calls within minutes.
audit_message_tone (identity:read) — Given a draft message the user is about to send, returns their established voice + the draft + an LLM task to identify off-tone phrases and suggest on-brand rewrites. Pair with detect_brand_voice first.
classify_intent (identity:read) — Maps free-form user text ("help me grow", "I have a launch") to the most relevant Shuuka prompt or tool. Returns the user's profile context + the prompt catalog + an LLM-ready classification instruction. Use before recommend_next_action when you need to bridge natural language → workflow.
dry_run_changes (identity:read) — Validates a write-tool call WITHOUT executing it. Returns would_succeed: true or would_fail with the specific error (validation, scope, plan-gateway, target-not-found). Use before destructive operations (delete_link, revoke_access) and before bulk loops — dry-run the first item to catch arg-shape bugs cheaply.
undo_recent_change (identity:read) — Lists your recent write tool calls (last 10 by default) and proposes the inverse call needed to reverse each. Does NOT execute the reversal — surfaces it so the user (via the host agent) can choose. Only operations made via MCP are visible; UI-driven changes don't show up.
get_setup_completeness (identity:read) — Walks 8 onboarding checkpoints (avatar, bio, ≥1 link, ≥1 verified link, theme picked, SEO meta set, ≥1 social platform, profile shared at least once) and returns a 0–100% completeness score plus the explicit list of missing items. Use to drive onboarding progress bars and "1 step away from complete" nudges.
interpret_my_score (identity:read) — Returns the user's identity score + risk score + their constituent contributors AND an LLM task to turn the numbers into a 2-sentence human paragraph that names what helped and what hurt the score.
get_my_timeline (identity:read) — Returns the chronological identity-events timeline for a profile: verifications won/lost, links added/removed, fake reports filed/resolved, plan upgrades, MCP grants issued/revoked. Each event has a stable event_type, entity_type, entity_id, actor_type, and ISO timestamp. Pair with get_identity_score — the timeline EXPLAINS the score number.

SEO

get_my_seo (seo:read) — Returns the user's per-profile SEO + social-meta overrides: title, description, keywords, OG image, Twitter card, noindex flag. These override the defaults that SeoMeta.php builds from the user's nickname/bio.
update_my_seo (seo:write) — Updates the user's SEO + social-meta overrides. Only the fields you pass are written; omit a field to leave it unchanged. Pass locale (e.g. "en", "de", "es") to update the per-language SEO translation rendered when a visitor opens the profile with ?lang=<locale>; omit locale to update the default SEO. noindex is a global flag and only applies when locale is omitted. Set noindex: true to remove the profile from search engines (renders as <meta name="robots" content="noindex">).

Links & Smart Routes

search_my_links (links:read) — Searches a profile's social links by handle, network name, or URL. Supports filters: verified (bool), is_backup (bool), archived (bool). Returns matching links with verification status, short_key (for click tracking), and display order. Use before update_link / delete_link / reorder_links.
get_top_links (analytics:read) — Returns a profile's top-performing social links — currently sorted by display order until per-link click tracking is wired into a queryable table. When click data becomes available, the same payload will sort by click count and the data_status field will switch to clicks_available. Pair with get_click_summary for the aggregate.
find_duplicate_links (links:read) — Detects functional duplicate links — same destination URL after stripping query strings + fragments + trailing slashes. Returns groups of duplicates so the user can delete_link the redundant ones. Pair with audit_my_routes for a full health check.
create_link (links:write) — Adds a new social network link to the authenticated user's profile. Requires the network name (e.g. "instagram") or numeric network_id, plus the handle. Returns the created link including its short_key (used for click tracking). Idempotency-Key required.
update_link (links:write) — Updates an existing social link belonging to the authenticated user. Mutable fields: handle, status (active|disabled), is_backup. The link URL is regenerated from the network template + new handle. Idempotency-Key required.
delete_link (links:write) — Deletes a social link belonging to the authenticated user. Reversible (soft-delete). The Identity Timeline records the deletion publicly. Idempotency-Key required.
reorder_links (links:write) — Reorders the authenticated user's social links. Pass an array of link IDs in the desired display order; orderBy is assigned in that sequence. IDs not in the array keep their current position. Idempotency-Key required.
set_leap_link (links:write) — Activates Leap Link — temporarily redirects the entire Shuuka profile to a single URL (launch / drop / event). The redirect auto-expires at expires_at if provided. Idempotency-Key required.
clear_leap_link (links:write) — Deactivates Leap Link — restores the normal profile view immediately. Idempotency-Key required.
list_smart_routes (smart_routes:read) — Lists the authenticated user's Smart Routes (short / affiliate / tracked links). Returns short_code, destination URL, click counts, and active status. Use to answer "how many short links do I have" or "which short links are most popular".
count_my_smart_routes_by_type (smart_routes:read) — Counts the authenticated user's Smart Routes split by classification: routes carrying any UTM/affiliate parameter ("affiliate") vs plain short routes ("regular").
audit_my_routes (links:read) — Audits a profile's active social links and surfaces issues: unverified accounts on platforms where verification is available, links missing handles, links with malformed URLs. Each link gets a health flag: good / warn / bad. Aggregate counts in the summary block. Use before launching a campaign and before set_leap_link.
generate_share_text (identity:read) — Returns the user's profile context + an LLM task to produce paste-ready share copy in 3 platform tones: twitter (punchy, ≤240 chars), instagram_bio (clean, ≤150 chars), email_signature (professional, multi-line). Pair with detect_brand_voice first.
generate_campaign_blurb (links:read) — Returns the user's brand voice + campaign URL + an LLM task to produce social-media copy variants for Instagram, Twitter, and LinkedIn — each tuned to that platform's norms and the user's established tone. Optionally pair with set_leap_link after — pick a variant, set Leap Link to the campaign destination.

Analytics & insight

get_click_summary (analytics:read) — Returns aggregate traffic metrics over a lookback window: profile visits, link clicks, approximate unique visitors. Use for "how is my profile performing this week / month?". For a per-link breakdown use get_top_links; for the dashboard-PDF level of detail use get_monthly_report.
get_anomalies (analytics:read) — Returns recent traffic anomalies detected for the profile (sudden spikes, drops, bot-like activity, regional surges). Sourced from the same backend that powers admin alerts. Use after get_click_summary reveals an unusual number to find the explanation.
get_attribution (analytics:read) — Breaks visits + clicks down by attribution channel (direct, organic-search, social-referral, paid, utm-campaign). Use to answer "which marketing efforts drive traffic". Pair with get_traffic_sources for raw referrers.
get_traffic_sources (analytics:read) — Returns top referrers + UTM sources + countries for the profile over a lookback range. Answers "where do my fans come from?". Pair with get_top_links to find which referrers drive which links.
get_growth_trends (analytics:read) — Returns visit-count trends across windows: this-week vs last-week, this-month vs last-month, this-year vs last-year. Each window has absolute value, delta_pct, and a label (rising / stable / declining). Deterministic threshold rules — no ML.
predict_my_growth (analytics:read) — Returns the user's last 6 months of visit data + plan thresholds + an LLM task to produce a trajectory analysis (not a statistical forecast). Use for self-coaching only — not a substitute for a real analytics service. Answers "when will I cross the 15k Free-tier traffic gate?".
summarize_my_month (analytics:read) — Returns the same data as get_monthly_report PLUS an LLM task that produces a 1-paragraph human narrative summarising what happened — wins, drops, top sources, attribution shifts — and recommends the single best next action.
get_monthly_report (analytics:read) — Returns the full Monthly Identity Report (the same data shown at /admin/analytics/reports and rendered into the PDF): traffic, clicks, top referrers, top countries, identity-event timeline, daily rollups, top smart-links, top affiliate-links, fake-report shield activity, and a built-in comparison block against the previous month. Use for "this month's performance", "compare May vs April", "did things improve". Free users above the 15k traffic gate get PLAN_REQUIRED on this tool.
compare_with_peers (analytics:read) — Compares the authenticated user's key metrics (visits, links count, verified count) to the median of peers. Default cohort = users created within ±30 days of the caller. Filters: match_category=true, match_country=true, match_language=true — multiple filters AND together for narrower cohorts. Returns a 50-peer privacy floor; never returns individual peer data.
find_attention_targets (analytics:read) — Returns ONLY time-critical items: expiring/expired Leap Link, pending fake-link reports about you, stalled verification requests (> 7d), failed webhook deliveries, expired team-member access. Smaller and more focused than recommend_next_action — use for "what do I need to handle today?".
explain_anomaly (analytics:read) — Given an anomaly_id from get_anomalies, pulls the surrounding context (traffic sources, top links, recent identity events around the same period) and returns an LLM task that produces a hypothesis + 2 confirmation actions.
recommend_next_action (analytics:read) — Returns a ranked list of concrete next actions tailored to the target profile's current state — without asking an LLM. Synthesises across profile completeness, link health, verification gaps, traffic trends, campaign hygiene, trust events, and plan usage. Each action has id, title, why, impact, action: {type, name, args} so the host agent can immediately act. Call this first for open-ended questions like "what should I do?", "make my profile better", "I don't know where to start".
next_post_idea (analytics:read) — Returns the user's recent activity timeline + traffic source breakdown + an LLM task to generate 3 content angles for their next post, each tied to a real signal in the data.

Themes & apps

get_my_theme (theme:read) — Returns the profile's currently active theme: theme_id, name, mode (light/dark), customizations (color overrides, font, layout). Use to understand visual config before suggesting apply_theme.
apply_theme (theme:write) — Switches the authenticated user's active profile theme. Pass theme_id from list_themes. Optional mode ("light"/"dark") and customizations overrides. The change is live immediately on the public profile. Idempotency-Key required.
list_themes (theme:read) — Lists all available theme templates with id, name, preview image, and plan requirement. Free templates work for everyone; Pro/Enterprise templates obey the plan-gateway rule.
list_my_apps (apps:read) — Lists every Shuuka marketplace app installed on the authenticated user's profile. Returns app id, name, version, install timestamp, and active status. Pair with discover_apps to find new ones.
discover_apps (apps:read) — Searches the Shuuka apps marketplace. Filter by category, search by name, or list trending. Returns apps the user can install_app next.
install_app (apps:write) — Installs a Shuuka marketplace app onto the authenticated user's profile. Pass app_id from discover_apps. Returns the installation_id needed for later uninstall_app calls. Idempotency-Key required.
uninstall_app (apps:write) — Uninstalls a marketplace app. Pass installation_id from list_my_apps. App data may be retained per the app's privacy policy — use request_data_export if you want a copy. Idempotency-Key required.

Verification & trust

list_my_verifications (verification:read) — Lists the authenticated user's verification requests (influencer / company / public-person / domain). Returns request status, type, and creation timestamp. Use to answer "which of my accounts still need verification".
request_verification (verification:request) — Submits a verification request for one of the authenticated user's social links. Use after audit_my_routes flagged unverified accounts. The request enters pending and resolves when the verification pipeline completes (typically < 7 days). Only Instagram, LinkedIn, TikTok, Spotify, YouTube, X, and GitHub are supported today. Step-up required.
cancel_verification (verification:request) — Cancels a pending verification request. After cancelling you can submit a new one with request_verification. Use this if you submitted with the wrong link or wrong type.
list_reports_about_me (trust:read) — Lists fake-account / impersonation reports submitted ABOUT the authenticated user's profile (Community Shield). Use to answer "are there fake profiles pretending to be me".
submit_fake_report (trust:report:write) — Submits a fake-impersonation report against another profile. Reports go in pending (or reported for authenticated MCP users) and are reviewed by Shuuka moderators — never auto-actioned. Maximum 3 reports per 24h per user (anti-abuse).
get_identity_score (gamification:read) — Returns the authenticated user's Identity Score: a 0–100 composite of profile completeness, verification coverage, app installations, and timeline depth. Includes the breakdown so an agent can suggest the highest-leverage improvements.
get_identity_risk_score (gamification:read) — Returns a 0–100 identity risk score for the authenticated user, derived from: pending fake-link reports, the velocity of new reports over the range, and the count of unverified active links. Higher = more risk.

Plan, goals & progress

get_my_plan (plan:read) — Returns the authenticated user's subscription plan, renewal date, gateway status (whether a Free user is over the 15k traffic threshold and gated out of Pro features), and a list of which scopes their CURRENT state can use.
get_plan_usage (plan:read) — Returns current usage vs plan limits across every metered Shuuka resource: links count, monthly visits (vs gateway threshold for Free), app installs, webhook subscriptions, MCP monthly API calls. Each row has used/limit/percent — quickly answers "am I about to hit a cap?".
list_my_achievements (gamification:read) — Returns the user's earned achievements/badges and their unlock dates. Pair with get_my_progress to see what's next.
get_my_progress (gamification:read) — Returns the user's gamification progress: total achievements unlocked, level/XP if available, next-to-unlock candidates with progress %. Use to surface "you're 1 verification away from 'Verified Trio' badge" type nudges.
list_my_goals (goals:read) — Lists the user's active growth goals (e.g. "1k profile visits this month"). Each row includes target, current value, % progress, and deadline.
set_goal (goals:write) — Creates a new analytics growth goal. Required: name (display label), metric_key (sessions | unique_visitors | total_views | total_clicks | direct_clicks | network_clicks), and target_value (positive integer). Optional: direction (gte default; lte for bounce-style), period (7d | 30d default | 90d | 12mo), and monetary_value + currency (ISO 4217) for revenue attribution. Track progress with track_goal_progress. Idempotency-Key required.
track_goal_progress (goals:read) — Returns the current progress for one goal: target, current value (recomputed live), progress %, days_remaining (vs deadline), and a pace flag (on_track | behind | exceeded).
next_unlock (gamification:read) — Returns the single most-imminent achievement the user is about to unlock — name, description, current progress %, and what specifically still has to happen. Differs from get_my_progress (a list of candidates) — this returns the closest one.

Data export

request_data_export (vault:export) — Triggers a GDPR-compliant data export of the authenticated user's Shuuka data: profile, links, smart routes, analytics, verification history, identity events, app installations, fake reports, webhooks. Returns an export_id; processed asynchronously. Poll with get_export_status until ready, then download via the returned URL. Step-up required.
get_export_status (vault:export) — Polls the status of a data export started with request_data_export. Returns status (pending|processing|ready|failed) plus a download URL when ready. Download URLs are short-lived signed URLs (typically valid for 24h).

Webhooks

list_my_webhooks (webhooks:read) — Lists the authenticated user's active webhook subscriptions. The HMAC secret is NEVER returned by this tool — only at create time. Returns last-success / last-failure timestamps to help diagnose delivery health.
subscribe_webhook (webhooks:write) — Creates a webhook subscription for the authenticated user. Shuuka POSTs a signed JSON envelope to url whenever any of the listed events happen. The HMAC secret is returned ONCE in the response — store it; receivers verify the X-Shuuka-Signature header against it. Idempotency-Key required. See Webhooks for the delivery contract.
delete_webhook (webhooks:write) — Deletes a webhook subscription. Pending deliveries that have not yet been attempted are dropped. Idempotency-Key required.

Tier 3 — workspace / agency

Available only on Enterprise plans. Operate across the manager's roster of accounts. Every Tier 3 tool requires that the calling user has an active AccountAccess relationship to the target accounts.

list_managed_accounts (workspace:read) — Lists every account the authenticated agency user has access to via active AccountAccess invitations, plus their own account. Each row includes role, restriction flag, and basic profile metadata. Use this to enumerate what an agency can manage before drilling into per-account analytics.
compare_accounts (workspace:analytics:read) — Compares multiple accounts in the workspace side-by-side on a chosen metric (clicks, page_views, unique_visitors, links_count, verified_count). The agency caller must have read permission on every account_id passed; restricted accounts and ones the caller has no access to are filtered out and listed in skipped[].
compare_voices (workspace:analytics:read) — For agencies managing multiple creators: returns the bio + verified networks for two managed accounts AND an LLM task that compares their brand voices, surfacing positioning overlap and differentiation opportunities. Use to ensure each creator has distinct positioning, or to find creators whose voices complement each other for collabs.
rank_accounts (workspace:analytics:read) — Ranks every account the agency manages by a metric (clicks, links_count, verified_count, verification_completeness, identity_score) over a date range. Returns top N (sort=desc) or bottom N (sort=asc). Restricted accounts and no-access accounts are silently dropped.
aggregate_fake_reports (workspace:trust:read) — Returns the count of fake-account / impersonation reports filed against every account the agency user manages, broken out by status. Use to answer "any impostor activity across my roster?".
invite_team_member (workspace:switch) — Invites another Shuuka user to manage the authenticated user's account with a given role (administrator, editor, viewer). Creates an AccountAccess row in pending state until the invitee accepts. Only the account owner can invite. Idempotency-Key required.
update_role (workspace:switch) — Promotes or demotes a team member's role on the authenticated user's account. Pass access_id and the new role. Only the account owner can change roles. Idempotency-Key required.
revoke_access (workspace:switch) — Revokes a team member's AccountAccess. Pass access_id from list_managed_accounts. Only the account owner can revoke. Idempotency-Key required.

Common errors

Error code	Meaning
`invalid_token`	Access token is missing, malformed, expired, or revoked.
`insufficient_scope`	Token does not include the scope this tool requires.
`step_up_required`	Fresh auth needed. Use the `auth_url` in `error.data`.
`plan_required`	The user's plan does not include this tool. Returns `required_plan`.
`validation_failed`	Argument schema mismatch (or missing `Idempotency-Key`).
`rate_limited`	Per-user, per-client, or plan-level rate limit hit.
`not_found`	The referenced resource (link, route, account) does not exist.
`traffic_gate`	Owner is on Free and over the monthly visit threshold.

Response shape

Every successful response follows JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type":"text","text":"..."}],
    "structuredContent": { /* tool-specific schema */ }
  }
}

structuredContent is the canonical machine-readable payload. content[0].text is a human-readable summary you can show in chat.

How a tool call looks​

Conventions used below​

Tier 1 — public reads​

Tier 2 — owner actions​

Identity & profile​

SEO​

Links & Smart Routes​

Analytics & insight​

Themes & apps​

Verification & trust​

Plan, goals & progress​

Data export​

Webhooks​

Tier 3 — workspace / agency​

Common errors​

Response shape​

Next​