Source: https://developers.tokportal.com/use-cases/ai-agents/cursor-mcp-tiktok/
Markdown: https://developers.tokportal.com/use-cases/ai-agents/cursor-mcp-tiktok.md

# TokPortal MCP Server for Cursor

The public MCP package is `tokportal-mcp`. It lets Cursor call generated TokPortal tools using your API key. This is a local stdio MCP server; your key is passed to the TokPortal API by the local process.

## Install

Add this to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "tokportal": {
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": {
        "TOKPORTAL_API_KEY": "sk_your_key_here"
      }
    }
  }
}
```

Get your key from the [Developer Portal](https://app.tokportal.com/developer/api-keys).

Reference: [MCP Server](https://developers.tokportal.com/mcp)

## Verify the connection

Ask Cursor:

> "Use the TokPortal MCP tools to show my credit balance."

If connected, Cursor should call `tokportal_get_credit_balance`.

## Create a bundle from Cursor

Use a prompt that forces Cursor to show the payload before executing:

> "Prepare a TokPortal request for a US TikTok bundle with 10 video slots and Advanced Niche Warming on 6 SaaS/tech targets. Show the exact MCP tool call first. Wait for confirmation before running it."

Expected tool shape:

```json
{
  "tool": "tokportal_create_bundle",
  "args": {
    "bundle_type": "account_and_videos",
    "platform": "tiktok",
    "country": "US",
    "videos_quantity": 10,
    "wants_advanced_warming": true,
    "advanced_warming_terms": [
      "saas tools",
      "b2b software",
      "productivity apps",
      "startup founder",
      "developer tools",
      "no code automation"
    ],
    "external_ref": "cursor-saas-us"
  }
}
```

`wants_advanced_warming: true` must travel with `advanced_warming_terms` (or `advanced_warming_terms_count`); on its own the target list is rejected with `ADVANCED_WARMING_FLAG_REQUIRED`. Targets are 3-30, in multiples of 3, each 2-50 characters. At the standard rate of 5 credits per target the 6 targets above are 30 credits, on top of 32 for the account and 2 per video slot: 32 + (10 x 2) + 30 = 82 credits.

Costs are returned by the API as `credits_charged` and `cost_breakdown`; do not hardcode them in your agent logic.

## Configure videos from project files

Cursor can read local files if you allow it. A useful workflow is:

> "Read `marketing/video-plan.md`, extract 5 captions and video URLs, then configure positions 1-5 on bundle `bnd_...`. Use `target_publish_date` starting 5 days from today, at most 3 videos on any single day. Show the batch payload before executing."

The earliest `target_publish_date` a bundle accepts is today + 3 days while its account is still being created, and today + 1 once the account is delivered or when the bundle runs on an existing account. A 4th video on the same day is rejected with `VIDEOS_PER_DAY_EXCEEDED`.

Expected API surface:

- `tokportal_batch_configure_bundle_videos`
- `PUT /bundles/{id}/videos/batch`
- body shape: `{ "videos": [...] }`

Reference: [Configure Videos](https://developers.tokportal.com/configure-videos)

## Monitor status and analytics

Useful tools:

| Tool                                     | Use                                         |
| ---------------------------------------- | ------------------------------------------- |
| `tokportal_get_bundle`                   | Inspect bundle status and configured fields |
| `tokportal_get_bundle_publish_readiness` | See why a bundle cannot publish yet         |
| `tokportal_list_accounts`                | List delivered accounts                     |
| `tokportal_get_account_analytics`        | Fetch account analytics when available      |
| `tokportal_list_account_video_analytics` | Fetch post-level analytics                  |

Analytics availability depends on the account/post state and your plan. See [Analytics](https://developers.tokportal.com/analytics).

## Operational guardrails

- Ask Cursor to confirm mutating calls before execution.
- Use `external_ref` to connect TokPortal records to your internal campaign IDs.
- Do not ask the agent to promise views, engagement, reach, or platform enforcement outcomes.
- Use [Webhooks](https://developers.tokportal.com/webhooks) for production monitoring instead of relying only on chat output.

Related docs: [SDKs & CLI](https://developers.tokportal.com/sdks-cli), [Media Upload](https://developers.tokportal.com/media-upload), [Python Quickstart](https://developers.tokportal.com/use-cases/platform-guides/python-quickstart), [Claude Code](https://developers.tokportal.com/use-cases/ai-agents/claude-code-social-media).