TokPortal + Claude via MCP

Claude-compatible MCP clients can run TokPortal tools through the public tokportal-mcp package. The server is generated from the public OpenAPI contract and uses your TokPortal API key.

Setup

Use this MCP server config:

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

For Claude Desktop, add it to claude_desktop_config.json. For Claude Code or another MCP client, add the same server definition to the client's MCP configuration.

Reference: MCP Server

Good prompts

For mutating API calls, ask Claude to show the payload first:

"Use TokPortal MCP. First check my credit balance. Then prepare, but do not execute, a payload for a TikTok bundle in the US with 5 videos, Advanced Niche Warming on 6 targets, and external_ref claude-q2-us."

Expected payload:

{
  "bundle_type": "account_and_videos",
  "platform": "tiktok",
  "country": "US",
  "videos_quantity": 5,
  "wants_advanced_warming": true,
  "advanced_warming_terms": [
    "saas tools",
    "productivity apps",
    "startup founder",
    "b2b software",
    "no code automation",
    "developer tools"
  ],
  "external_ref": "claude-q2-us"
}

wants_advanced_warming: true is mandatory whenever advanced_warming_terms or advanced_warming_terms_count is present; without it the call is rejected with ADVANCED_WARMING_FLAG_REQUIRED and nothing is charged. Targets are 3-30, in multiples of 3, each 2-50 characters, and duplicates are not silently dropped (ADVANCED_WARMING_TERMS_REJECTED). At the standard rate of 5 credits per target, the 6 targets add 30 credits to the 32 for the account and 2 per video slot: 32 + (5 x 2) + 30 = 72 credits. Ask Claude to read tokportal_get_credit_costs for the effective rate rather than quoting prices from memory.

After confirmation, Claude can call tokportal_create_bundle.

Supported workflows

Workflow	Tools / endpoints
Check credits	`tokportal_get_credit_balance`, `GET /credits/balance`
Create bundles	`tokportal_create_bundle`, `POST /bundles`
Create several bundles in one country	`tokportal_create_bundles_bulk`, `POST /bundles/bulk`
Configure account profile	`tokportal_configure_bundle_account`, `PUT /bundles/{id}/account`
Configure videos	`tokportal_configure_bundle_video`, `tokportal_batch_configure_bundle_videos`
Upload media	`tokportal_upload_video`, `tokportal_upload_video_direct`, `tokportal_upload_image`
Publish	`tokportal_publish_bundle`, `POST /bundles/{id}/publish`
Analytics	`tokportal_get_analytics_dashboard`, `tokportal_get_account_analytics`, `tokportal_list_account_video_analytics`

See MCP available tools for the complete generated list.

CSV and media workflows

The CSV import endpoint is multipart:

POST /bundles/{id}/videos/import-csv

If your MCP client cannot easily provide multipart files, use one of these alternatives:

Configure videos in JSON with tokportal_batch_configure_bundle_videos.
Upload media through Media Upload, then pass returned URLs/paths to video configuration.
Use the CLI or Node SDK for file-heavy workflows.

Monitoring

For production work, combine Claude with:

Webhooks for lifecycle events
tokportal_get_bundle_publish_readiness before publishing
Analytics after posts are live

Do not treat AI output as a guarantee of campaign performance. The MCP server executes supported TokPortal API operations; views, reach, and account health depend on platform behavior and content quality.

Related guides: Cursor MCP, OpenClaw, Python Quickstart.