Connect Codex to TikTok Ads MCP: Setup and First Analysis

This tutorial takes you through connecting Codex to the official TikTok for Business Ads MCP server. When you finish, Codex can list the advertiser accounts you may access and analyze the last seven complete calendar days.

Setup normally takes 5–10 minutes. It does not require code, a TikTok developer app, or an API key.

What you will have when you finish

• TikTok Ads appears as connected in Codex's MCP server list.
• Codex can list the TikTok advertiser accounts available to your user.
• Codex can return the account time zone, currency, and seven complete days of performance.
• You have completed a reviewable read-only query without changing ad configuration.

Before you start

Requirement	Minimum	How to verify it
Codex	Desktop app with Codex installed and available	You can open Codex and start a new chat
TikTok for Business user	Able to sign in	Sign in once in your default browser
Ad-account access	Permission to view the target account and reports	View recent data in TikTok Ads Manager
Browser	Able to complete OAuth and return to the app	Temporarily disable popup or sign-in blockers
Account context	Target account name, time zone, and currency are known	Check the account settings in Ads Manager

This guide uses the Codex desktop interface. If needed, install and sign in by following the official OpenAI desktop app documentation.

Step 1: Open Codex

1. Open the desktop app and sign in to your OpenAI account.
2. Select Codex.
3. Select New chat.
4. Send a test message to confirm the session works.

Checkpoint: You can see the Codex composer and receive a response.

Step 2: Verify the TikTok ad account

1. Sign in to TikTok Ads Manager in your default browser.
2. Switch to the account you want to analyze.
3. Record its name, advertiser ID, time zone, and currency.
4. Open reporting and confirm that your user can see recent data.

Checkpoint: The current browser user already has view access to the target account. OAuth does not grant new ad-account permissions.

Step 3: Add the TikTok Ads MCP server

1. Open Settings in Codex.
2. Select MCP servers.
3. Select Add server.
4. Enter these values:

Field	Value
Name	TikTok Ads
Type	Streamable HTTP
Server URL	https://business-api.tiktok.com/open_mcp/tt-ads-mcp-layer

5. Save the server.
6. Select Restart so Codex reloads the MCP configuration.

This is TikTok's Progressive Disclosure endpoint. It loads core tools first and discovers more when needed, which keeps initial setup light.

Checkpoint: TikTok Ads appears in the MCP server list. A “needs authentication” status is expected.

If your version does not yet show the visual add-server control, edit the global ~/.codex/config.toml file:

[mcp_servers.tiktok_ads]
url = "https://business-api.tiktok.com/open_mcp/tt-ads-mcp-layer"

Save the file and restart Codex. Do not commit the global configuration to a project repository.

Step 4: Complete TikTok OAuth

1. Select Authenticate beside TikTok Ads.
2. In the browser, sign in as the TikTok for Business user with access to the target account.
3. Review the permissions displayed by TikTok.
4. Approve access and wait for the browser to return to Codex.
5. Reopen the MCP server list or restart once if the status does not refresh.

Never paste a TikTok password, cookie, access token, or callback URL into Codex. A normal OAuth flow does not require you to transfer those credentials manually.

Checkpoint: TikTok Ads is enabled or connected and no longer asks for authentication.

Step 5: Verify the MCP tools

Start a new Codex chat and enter:

/mcp

Find TikTok Ads in the result and confirm that tools are available. A smaller tool count is normal with Progressive Disclosure.

Do not skip this check. If the server is not connected, a general question may produce generic advice instead of live account data.

Step 6: List accessible advertiser accounts

Paste this prompt:

Use only read operations from TikTok Ads MCP. List the TikTok advertiser accounts available to the currently authorized user.

For each account, return:
- account name
- advertiser ID
- account status
- time zone
- currency

Mark fields that cannot be retrieved as "unavailable." Do not infer them.
Do not create, edit, pause, or delete any campaign, ad group, ad, audience, budget, bid, or targeting setting.

Successful result: Codex returns at least one account you recognize. Compare its name, advertiser ID, time zone, and currency with Ads Manager, then copy the advertiser ID you will analyze.

Step 7: Run the first read-only analysis

Replace 1234567890123456789 with the real advertiser ID:

Use only read operations from TikTok Ads MCP to analyze advertiser ID 1234567890123456789.

Requirements:
1. First retrieve and confirm the account name, advertiser ID, time zone, and currency.
2. Use the last seven complete calendar days ending yesterday in the account time zone. Exclude today.
3. Summarize by campaign: status, spend, impressions, clicks, CTR, CPC, conversions, CVR, CPA, conversion value, and ROAS.
4. Sort by spend descending and include an account-total row.
5. State the conversion event and attribution basis used.
6. Mark metrics the API does not return as "unavailable." Do not guess or treat missing values as zero.
7. End with no more than three anomalies for human review and show the supporting data.

Do not create, edit, pause, or delete any campaign, ad group, ad, audience, budget, bid, or targeting setting. Do not execute optimization recommendations.

How to know the result is usable

The response should state:

• Account name and advertiser ID.
• Exact start and end dates, with today excluded.
• Account time zone and currency.
• Aggregation level and sort order.
• Conversion event, attribution basis, and filters.
• Which values are truly zero and which metrics are unavailable.

Ask Codex to supply missing context before using the result to make a budget decision.

Fast troubleshooting order

TikTok Ads is missing from the MCP list

Return to Settings → MCP servers, confirm the server is saved and enabled, verify that the URL has no spaces, and select Restart.

Authentication loops back to sign-in

Sign in to the correct TikTok for Business user in your default browser, allow popups and local callbacks, then authenticate again from Codex.

The account list is empty

Make sure the OAuth user is the same user who can see the account in Ads Manager. For a team account, ask a Business Center administrator to check the user assignment.

The server appears but has no tools

Verify the Streamable HTTP type and tt-ads-mcp-layer endpoint, then restart Codex. If needed, remove the incorrect entry and add it again with the exact values above.

The query succeeds but returns no data

Try the last three complete calendar days, confirm that the account had spend, and ask Codex to show the actual dates and filters used.

The numbers differ from Ads Manager

Compare account time zone, date boundaries, currency, conversion event, attribution window, and reporting level. A UI view that includes today is not directly comparable with complete days ending yesterday.

See TikTok Ads MCP Troubleshooting for the full diagnostic flow.

Credential and execution safety

• Never paste passwords, cookies, access tokens, or OAuth callback URLs into prompts.
• Do not expose full advertiser IDs, client names, or business data in public screenshots.
• Use read operations for the first workflow and explicitly prohibit writes.
• Reject a request to call create, update, pause, or delete tools during this tutorial.
• Put budget, bid, targeting, and status changes in a separate, human-approved workflow.

Official references

• OpenAI: Connect Codex to MCP servers
• OpenAI: Install and use the desktop app
• TikTok for Business: About TikTok for Business MCP Server

After setup, continue with Analyze TikTok Ads Performance with AI to turn the first query into a repeatable review.