TikTok Ads

Go to the TikTok Marketing API portal and create a developer account. If you already have a TikTok Ads Manager account, you can use the same credentials to sign in and register as a developer.

In the developer portal, go to My Apps → Create App. Give it a descriptive name like ShopMCP. When prompted for permission scopes, select:

• Ad Account Management — read access (required for all read tools)
• Ad Management — read access (required for campaign and ad group queries)

Do not grant write scopes unless you plan to enable write tools later. ShopMCP's read tools only need read-level access.

TikTok requires all Marketing API apps to pass review before they can access production data. Click Submit for Review — approval typically takes 1-3 business days.

While waiting, you can use Sandbox access to test the integration with sample data. Sandbox mode is available immediately after app creation and does not require review approval.

Once your app is approved (or for sandbox testing), collect the following from the developer portal:

• App ID — found on the app's Basic Info page
• App Secret — found on the app's Basic Infopage. Treat this like a password — it's used to refresh access tokens.
• Access Token — generate one from the Tools section of the developer portal. Select the advertiser account you want to connect and click Generate.

Your Advertiser ID is the numeric ID displayed at the top of TikTok Ads Manager. This identifies the specific ad account ShopMCP will query. Copy it — you'll need it in the next step.

Open Settings → Integrations → TikTok Ads and fill in:

• App ID — from step 4
• App Secret — from step 4
• Access Token — from step 4
• Advertiser ID — from step 5

On submit, ShopMCP calls /advertiser/info/ on the TikTok Marketing API to confirm the credentials are valid and the Advertiser ID is accessible. A successful verification persists the credentials encrypted-at-rest (KMS envelope) and flips the TikTok Ads module to Connected for every API key in the workspace.

ShopMCP's TikTok Ads package includes three write tools — tiktok_ads_pause_campaign, tiktok_ads_resume_campaign, and tiktok_ads_update_budget. These are compiled in but never registered in v1. The runtime calls registerTikTokAdsTools({ allowWrites: false }) regardless of plan tier.

Each write tool is locked to a hand-written, field-level input allowlist. For example, tiktok_ads_update_budget accepts budget and budget_mode — and nothing else. Campaign objective changes, audience targeting updates, and creative modifications are all rejected at the input schema layer before any HTTP request is built. This is deliberate: if a prompt injection convinces the LLM to call the tool with disallowed fields, the Zod validator drops the request on the floor.

TikTok Marketing API access tokens expire every 24 hours. ShopMCP automatically refreshes them using your App ID and App Secret before they expire — no manual intervention is needed.

• Access token (24-hour lifetime). ShopMCP detects expiry and calls the TikTok OAuth refresh endpoint automatically. You will never need to manually generate a new access token after the initial setup.
• Refresh token (longer lifetime).TikTok's refresh tokens have a longer validity period. ShopMCP stores and rotates them automatically. If a refresh token expires (rare, but possible after extended inactivity), you'll need to generate a new access token from the developer portal and reconnect.
• Revoke access.To fully revoke ShopMCP's access, delete the app in the TikTok Developer Portal or remove the authorized advertiser. ShopMCP's next API call will fail and surface an error to the user.

• Error code 40001 — "Invalid access token" — the access token has expired or been revoked. If ShopMCP's auto-refresh is failing, check that the App Secret in ShopMCP matches the one in the developer portal. If it was rotated, update it in Settings → Integrations → TikTok Ads.
• Error code 40002 — "Insufficient permissions" — the app is missing a required permission scope. Go to the developer portal, edit the app, and ensure Ad Account Management (read) and Ad Management (read) are both granted. You may need to resubmit for review if you add new scopes.
• Error code 40100 — "Rate limit exceeded" — TikTok is throttling your API calls. ShopMCP does not retry automatically on rate limit errors by design. Wait the duration indicated in the error response and try again.
• "App not approved"— the Marketing API app has not passed TikTok's review yet, or was rejected. Check the app's status in the developer portal. Use Sandbox mode for testing while the review is pending.
• "Advertiser not found" or empty results — the Advertiser ID is incorrect or the app does not have access to that advertiser. Verify the numeric ID in TikTok Ads Manager and ensure the app is authorized for that specific advertiser account.