Source: https://developers.tokportal.com/use-cases/ai-agents/claude-code-social-media/
Markdown: https://developers.tokportal.com/use-cases/ai-agents/claude-code-social-media.md

# 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:

```json
{
  "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](https://developers.tokportal.com/mcp)

## 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:

```json
{
  "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](https://developers.tokportal.com/mcp#what-you-can-do) for the complete generated list.

## CSV and media workflows

The CSV import endpoint is multipart:

```http
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](https://developers.tokportal.com/media-upload), then pass returned URLs/paths to video configuration.
- Use the [CLI or Node SDK](https://developers.tokportal.com/sdks-cli) for file-heavy workflows.

## Monitoring

For production work, combine Claude with:

- [Webhooks](https://developers.tokportal.com/webhooks) for lifecycle events
- `tokportal_get_bundle_publish_readiness` before publishing
- [Analytics](https://developers.tokportal.com/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](https://developers.tokportal.com/use-cases/ai-agents/cursor-mcp-tiktok), [OpenClaw](https://developers.tokportal.com/use-cases/ai-agents/openclaw-tiktok-posting), [Python Quickstart](https://developers.tokportal.com/use-cases/platform-guides/python-quickstart).