# Toneden — how to use (mcp.ai)

Connect your Toneden account and use 26 tools for social media marketing straight from your AI agent. Connect in one click, no API key needed. ToneDen automates social media campaigns, advertising, and landing pages, particularly for music promoters and event organizers looking to boost audience reach.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_toneden?ms=1787296020000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `toneden_create_advertising_campaign`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/toneden`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/toneden/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/toneden/create/advertising/campaign` — Tool to create a ToneDen advertising campaign on Facebook or Google platforms. Use when you need to launch a new ad campaign with specified budget, targeting, and creatives.
  - body: { title?: string, status?: string, target?: string, currency?: string, platform: string, audiences: object[], creatives: object, objective?: string, targeting?: object, budget_type: string, target_type?: string, budget_amount: number, end_timestamp?: integer, is_continuous?: boolean, report_emails?: string[], optimization_id?: string, start_timestamp?: integer, target_link_url?: string, external_poster_id?: string, instagram_account_id?: string, external_ad_account_id: string, disable_all_notifications?: boolean }
- `POST https://api.mcp.ai/api/toneden/create/attachment` — Tool to create an attachment. Use when you need to programmatically create a social unlock or contest attachment after gathering all required parameters.
  - body: { type: string, platform?: string, platforms?: string[], unlock_text?: string, unlock_type?: string, download_url?: string, messenger_page_id?: string, stream_unlock_url?: string }
- `POST https://api.mcp.ai/api/toneden/create/link` — Tool to create a ToneDen link. Use when you have the target_type and, if needed, the services array. Supports creation of links for music, podcast, livestream, event, tour, biglink, fundraiser, smartl
  - body: { services?: object[], target_type: string }
- `POST https://api.mcp.ai/api/toneden/delete/advertising/campaign` — Deletes a ToneDen advertising campaign by ID using DELETE /advertising/campaigns/{campaignID}.
  - body: { campaignID: string|integer }
- `POST https://api.mcp.ai/api/toneden/delete/link` — Deletes a ToneDen link by ID using DELETE /links/{linkID}.
  - body: { link_id: string|integer }
- `POST https://api.mcp.ai/api/toneden/delete/playbook/campaign` — Deletes a ToneDen playbook campaign by ID using DELETE /playbooks/campaigns/{campaignID}.
  - body: { campaign_id: string|integer }
- `POST https://api.mcp.ai/api/toneden/expand/link/template` — Tool to expand a ToneDen link template. Use when you need to retrieve the full template link with your tracking pixels and optional service links. Provide a URL to generate platform services for music
  - body: { url?: string }
- `POST https://api.mcp.ai/api/toneden/get/advertising/campaign` — Retrieve a specific advertising campaign by its ID using ToneDen's API. Endpoint: GET /advertising/campaigns/{campaignID} Notes: - This endpoint does not require a userID in the path per official docs
  - body: { campaignID: string }
- `POST https://api.mcp.ai/api/toneden/get/advertising/campaign/creative/insights` — Retrieve creative performance insights for a specific advertising campaign using ToneDen's API. Endpoint: GET /advertising/campaigns/{campaignID}/creativeInsights. Note: Endpoint uses camelCase `creat
  - body: { campaignID: string }
- `POST https://api.mcp.ai/api/toneden/get/advertising/campaign/insights` — Retrieve performance insights for a specific advertising campaign using ToneDen's API. Endpoint: GET /advertising/campaigns/{campaignID}/insights.
  - body: { campaignID: string }
- `POST https://api.mcp.ai/api/toneden/get/attachment` — Tool to retrieve an attachment by ID. Use when you need to fetch details of an existing attachment by its ID.
  - body: { attachmentID: string }
- `POST https://api.mcp.ai/api/toneden/get/attachment/entries/time/series` — Tool to fetch time-series entry statistics for a specific attachment. Use when you need chronological entry data points for an attachment.
  - body: { attachmentID: string }
- `POST https://api.mcp.ai/api/toneden/get/attachment/entries/totals` — Tool to fetch summary counts of entries for an attachment. Use when you need aggregate entry counts over day, week, month, and lifetime.
  - body: { attachmentID: string }
- `POST https://api.mcp.ai/api/toneden/get/attachment/unlocks/by/platform` — Tool to fetch counts of unlocks by platform for a specific attachment. Use when you need a breakdown of unlocks across platforms like Spotify, Twitter, etc.
  - body: { attachmentID: string }
- `POST https://api.mcp.ai/api/toneden/get/attachment/unlocks/time/series` — Tool to fetch time-series unlock statistics for a specific attachment. Use when you need chronological unlock data points for an attachment.
  - body: { attachmentID: string }
- `POST https://api.mcp.ai/api/toneden/get/link` — Tool to retrieve a specific ToneDen link by its ID. Use when you need to fetch details about an existing link.
  - body: { linkID: integer }
- `POST https://api.mcp.ai/api/toneden/get/link/insights` — Tool to retrieve detailed insights for a ToneDen link. Use when you have a link ID and need metrics such as clicks, clickthroughs, email clicks, etc.
  - body: { linkID: string, metric: string, end_date?: string, start_date?: string, aggregate_geo?: string, for_distinct_fans?: boolean, aggregate_interval?: string, aggregate_by_service?: boolean, aggregate_by_referrer?: boolean }
- `POST https://api.mcp.ai/api/toneden/get/link/insights/overview` — Tool to retrieve a summary overview of a link's performance insights. Use when you have a link ID and need aggregated metrics across platforms.
  - body: { linkID: string }
- `POST https://api.mcp.ai/api/toneden/get/user` — Tool to retrieve a specific ToneDen user by ID. Use when you need to fetch user profile information or details about the currently authenticated user.
  - body: { user_id: string }
- `POST https://api.mcp.ai/api/toneden/list/playbook/campaigns` — Tool to list playbook campaigns. Use when you need to retrieve a paginated list of all playbook campaigns.
  - body: { limit?: integer, offset?: integer }
- `POST https://api.mcp.ai/api/toneden/list/user/attachments` — Tool to list attachments for a user. Use when you need to retrieve social unlocks or contest attachments belonging to a specific user.
  - body: { type: string, limit?: integer, offset?: integer, userID: string }
- `POST https://api.mcp.ai/api/toneden/list/user/lists` — Tool to retrieve a list of a user's advertising user lists. Use when you need to fetch all user lists (custom audiences) for a specific ToneDen user.
  - body: { userID: string }
- `POST https://api.mcp.ai/api/toneden/update/attachment` — Tool to update an existing attachment. Use when you need to flexibly modify any attachment field (or add custom fields) after its creation.
  - body: { type?: string, update?: object, platform?: string, link_path?: string, platforms?: string[], unlock_text?: string, unlock_type?: string, attachmentID: string, download_url?: string, messenger_page_id?: string, stream_unlock_url?: string }
- `POST https://api.mcp.ai/api/toneden/update/playbook/campaign` — Updates a ToneDen playbook campaign by ID using PUT /playbooks/campaigns/{campaignID}. Note: ToneDen's public docs do not expose the full request body schema for updates. This action sends a flexible 
  - body: { name?: string, notes?: string, budget?: number, status?: string, update?: object, end_date?: string, metadata?: object, start_date?: string, campaign_id: string|integer }
- `POST https://api.mcp.ai/api/toneden/update/user` — Tool to update a ToneDen user's profile. Use when you need to modify user details (e.g., name, location, or settings) after fetching them.
  - body: { city?: string, about?: string, state?: string, policy?: string, country?: string, user_id: string, profile_url?: string, display_name?: string, timezone_name?: string, additional_emails?: string[], interface_settings?: object, advertising_settings?: object }
- `POST https://api.mcp.ai/api/toneden/validate/link/path` — Tool to check if a link path/subdomain combination is unique and valid. Use when creating or editing a ToneDen link to verify the path is available.
  - body: { path: string, link_id?: integer, subdomain?: string }

## Example prompts
- "What can I do in Toneden?"
- "Show me a summary of my Toneden account"

## More
- Page: https://mcp.ai/toneden
- Agent spec (llms.txt): https://mcp.ai/toneden/llms.txt
- Postman collection: https://mcp.ai/toneden/postman.json