TikTok Ads MCP Troubleshooting: Connection, OAuth, Permissions, and Data

Use this guide to diagnose the most common TikTok Ads MCP connection and data failures. Start at the highest layer and move down: changing a prompt cannot fix a disconnected server, and reinstalling a client cannot fix a missing ad-account assignment.

Most investigations take 5–20 minutes. Every verification below reads configuration, connection state, or ad data only.

Record this context first

Information	Example	Safe to share publicly?
Client and version	Codex desktop, Claude Code version, Cursor version	Yes
Operating system	macOS, Windows, Linux	Yes
Server mode	Progressive or Full Disclosure	Yes
Server endpoint	Official endpoint	Yes
Error time	2026-08-20 10:30 with time zone	Yes
Error text	Complete error code and message	Yes, after redaction
Advertiser ID	Full ID	No; keep only the last four digits
Password, cookie, token, callback URL	Any credential	Never save or share

Redact client names, full advertiser IDs, business data, and tokens from screenshots.

Map the symptom to a layer

Symptom	Most likely layer	Check first
Server missing from MCP list	Client configuration	Endpoint, scope, save, and reload
Server present but zero tools	Tool initialization	Transport, endpoint suffix, client restart
Repeated sign-in	OAuth	Browser user, popup, callback, auth state
Connected but no accounts	Account permission	OAuth user versus Ads Manager user
Only some accounts appear	Business Center assignment	Per-account user assignment
Account exists but report is empty	Query scope	Advertiser ID, dates, time zone, status, filters
Report differs from the UI	Metric definition	Time zone, today, attribution, event, currency, level
Slow or timed-out query	Request size	Tool mode, dates, dimensions, batching

Step 1: Verify the official server endpoint

TikTok currently provides:

Mode	Endpoint	Behavior
Progressive Disclosure	https://business-api.tiktok.com/open_mcp/tt-ads-mcp-layer	About 40 core tools initially; more discovered on demand
Full Disclosure	https://business-api.tiktok.com/open_mcp/tt-ads-mcp-flat	About 400 tools loaded at connection time

Common configuration mistakes:

• Using the TikTok Ads Manager webpage as the MCP endpoint.
• Omitting https:// or the final layer/flat segment.
• Copying a space, quote, or punctuation with the URL.
• Selecting local STDIO instead of remote Streamable HTTP/HTTP.
• Defining the same server name twice with different endpoints.

Checkpoint: Only the intended TikTok Ads entry exists, with the exact transport and endpoint.

Step 2: The server is missing from the client

Check in order:

1. The add-server action was saved.
2. The intended global, user, or project scope was used.
3. The client window or process was reloaded.
4. The MCP status page, not only the chat tool list, was checked.
5. Configuration syntax is valid: no trailing JSON comma or duplicate TOML table.
6. An organization policy is not blocking personal MCP servers.

Client entry points:

• Codex: Settings → MCP servers, or enter /mcp.
• Claude Code: run claude mcp list, then enter /mcp in a session.
• Cursor: Customize → MCP, and verify that the server is enabled.

Checkpoint: The server appears in status. “Authentication required” is not a configuration failure.

Step 3: The server appears but shows zero tools

1. Confirm Streamable HTTP or HTTP transport.
2. Verify the official layer/flat suffix.
3. Reload the client to initialize the server again.
4. Give Full Disclosure time to load its larger tool catalog.
5. Open error details and record the HTTP status or initialization error.
6. If the team uses a tool allowlist, make sure reporting read tools are allowed.

A shorter initial list with Progressive Disclosure is expected. The failure case is an explicit zero-tool state or initialization error.

Checkpoint: At least the tools required to read accounts or reports are available.

Step 4: OAuth loops or the callback fails

Work through this sequence:

1. Sign out of the wrong TikTok user in the default browser.
2. Sign in as the TikTok for Business user who can access the target ad account.
3. Allow popups and local callbacks for the current sites.
4. Temporarily disable extensions that block sign-in or cross-site redirects.
5. Start authentication again from the TikTok Ads server entry.
6. Wait for the browser redirect to complete before returning to the client.
7. Refresh the MCP page or restart once if the client displays stale state.

Only if those steps fail, use the client's Clear authentication or Disconnect control for TikTok Ads and authorize again. Do not remove unrelated MCP connections.

Never send a callback URL, authorization code, or token in chat. Some clients ask you to paste the callback URL into a dedicated authentication prompt; use only that prompt.

Checkpoint: Status changes from authentication required to connected, and the browser no longer loops.

Step 5: Authentication succeeds but the account list is empty

Verify the same user in Ads Manager:

1. Open Ads Manager.
2. Confirm the user identity in the account selector.
3. Switch to the target ad account.
4. Confirm that a report opens.
5. Return to the client and run a minimal account-list query.

Minimal prompt:

Use only read operations from TikTok Ads MCP. List the advertiser accounts available to the currently authorized user.
Return only account name, advertiser ID, status, time zone, and currency.
Mark unavailable fields explicitly. Do not infer or change anything.

If the account is visible in Ads Manager but MCP still returns nothing, record the user, client time, server mode, and error text, then authorize once more.

Step 6: Only some ad accounts appear

This usually comes from Business Center asset assignment:

• Membership in a Business Center does not automatically grant every ad account.
• A partner relationship does not assign each asset to every member.
• OAuth carries only the current user's existing account access.
• An account may have been removed, frozen, or managed by another login identity.

Ask a Business Center administrator to inspect the user assignment and view permission for each missing ad account. After a permission change, verify it in Ads Manager before refreshing or reauthorizing MCP.

Checkpoint: The MCP account scope matches Ads Manager for the same user.

Step 7: A tool returns a permission error

Record:

• The read request that failed.
• Last four digits of the advertiser ID.
• HTTP or platform error code.
• Whether the same level is visible in Ads Manager.
• Whether the same query works for another account.

If one account fails, prioritize its assignment and status. If every account fails, prioritize OAuth state, team policy, or server connection.

Do not grant administrator access just to bypass diagnosis. Confirm the minimum report-view permission first.

Step 8: Queries time out, load slowly, or hit a rate limit

Reduce the request before retrying:

1. Query one advertiser account.
2. Use the last three complete calendar days.
3. Fetch campaigns only, not ad groups and ads.
4. Keep spend, impressions, clicks, and conversions only.
5. Add levels and metrics in batches after the small query succeeds.

Full Disclosure has more tools to process at first connection. Progressive Disclosure may discover tools during a request. A short wait in either case is not automatically a failure.

When rate-limited, stop repeated calls and observe the retry timing shown by the client or server. Do not run multiple identical large reports in parallel.

Step 9: The account exists but the report is empty

Run a minimum-data query:

Use only read operations from TikTok Ads MCP to query advertiser ID 1234567890123456789.
Use the last three complete calendar days ending yesterday in the account time zone.
At campaign level, return only status, spend, impressions, clicks, and conversions. State the exact dates, time zone, currency, and filters used.
Distinguish numeric zero, no returned rows, and an unavailable metric. Do not change anything.

Then check:

• The advertiser ID belongs to the authorized user.
• The account actually spent during those dates.
• A status, objective, or level filter did not exclude everything.
• The account time zone did not move the dates into an empty period.
• The account is not paused, frozen, or awaiting launch.
• The conversion event applies to the campaign objective.

Checkpoint: Even with no conversions, the response explains whether spend or impressions exist and why rows may be missing.

Step 10: The report differs from Ads Manager

Align the exact conditions:

1. Advertiser ID.
2. Account time zone.
3. Start and end dates, including whether today is present.
4. Currency.
5. Report level: account, campaign, ad group, or ad.
6. Status and other filters.
7. Click definition.
8. Primary conversion event.
9. Attribution window and reporting basis.
10. Data delay and deduplication.

The most common difference is an Ads Manager view that includes today versus a prompt using complete days ending yesterday. Conversions and conversion value may also arrive later than spend and clicks.

Ask the AI to print every query parameter before the table, then manually reproduce one or two high-spend campaign rows in Ads Manager.

Step 11: Decide whether to switch loading modes

Do not treat endpoint switching as a general fix. Try it only when:

• Full Disclosure clearly overwhelms the client with its tool count.
• Progressive Disclosure cannot discover a tool required for a specific task.
• TikTok or the client documentation recommends the other mode for that client.

Keep only one TikTok Ads entry while switching. Reauthorize it, run the account list, and then run the minimum report. Do not configure both flat and layer under the same name.

Step 12: Build a minimal reproduction record

If the issue remains, collect:

Client and version:
Operating system:
Server mode: Progressive Disclosure / Full Disclosure
Server endpoint:
Time of failure and time zone:
Server status:
Tool count:
OAuth status:
Advertiser ID: last four digits only
Minimal read-only prompt:
Complete error text: sensitive information removed
Same user can see the account in Ads Manager: yes / no
Last successful time:

Before sending it to support, remove passwords, cookies, tokens, authorization codes, full callback URLs, full advertiser IDs, client names, and business data.

Verify recovery in this order

After a fix, do not jump directly to a large report:

1. Server appears in the MCP list.
2. Authentication status is connected.
3. Tool list is not empty.
4. Minimal account list returns the correct account.
5. A three-complete-day campaign report returns data.
6. A spot-checked Ads Manager spend value matches the same date conditions.
7. Only then restore the complete seven- or 14-day analysis.

Stop at the first failing layer and diagnose it.

Credential and execution safety

• Never put passwords, cookies, tokens, authorization codes, or full callback URLs in logs, screenshots, or prompts.
• Troubleshooting uses read operations only; reject every write approval.
• Clear authentication or configuration only for TikTok Ads, not all connections.
• Keep team-account permissions least-privileged; do not grant unnecessary administrative access for debugging.

Official reference and client guides

• TikTok for Business: About TikTok for Business MCP Server
• Connect Codex to TikTok Ads MCP
• Connect Claude Code to TikTok Ads MCP
• Connect Cursor to TikTok Ads MCP
• Analyze TikTok Ads Performance with AI