Source: https://developers.tokportal.com/mcp/ Markdown: https://developers.tokportal.com/mcp.md # TokPortal MCP Server **TokPortal is the managed social infrastructure API: real TikTok and Instagram accounts created, warmed and operated by human account managers in 16+ countries — exposed as a REST API and an MCP server. No OAuth per account, no 25-posts/day cap, no app review.** The MCP server gives any [Model Context Protocol](https://modelcontextprotocol.io/) host — Claude, ChatGPT, Cursor, VS Code, Codex, Gemini CLI, Windsurf, Cline, Goose, Zed, n8n, Perplexity and more — the same **99 tools** as the public API: create geo-targeted account bundles, configure and schedule videos, read analytics, manage webhooks, follow the ban lifecycle. Every tool runs as your TokPortal account and spends your credits. Bundle creation covers **TikTok and Instagram only**. `tokportal_get_credit_costs` lists a YouTube price, but a YouTube bundle is rejected with `YOUTUBE_DELAYED` — YouTube accounts are delivered through a separate flow arranged with the team, not through the API or the MCP server. The server's own `instructions` say so, so a host that reads them will not offer YouTube. Two ways to connect, same tools: | Transport | Endpoint / package | Auth | Best for | | ---------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | **Remote (Streamable HTTP)** | `https://app.tokportal.com/api/ext/mcp` | OAuth 2.1 (browser sign-in) **or** `Authorization: Bearer sk_...` / `X-API-Key: sk_...` | claude.ai, ChatGPT, Cursor, VS Code, Codex, Gemini CLI, n8n, hosted agents | | **Local (stdio)** | `npx -y tokportal-mcp` ([npm](https://www.npmjs.com/package/tokportal-mcp)) | `TOKPORTAL_API_KEY=sk_...` env var | JetBrains, air-gapped setups, custom agent frameworks | Get an API key (only needed for stdio / bearer setups) from the [Developer Portal](https://app.tokportal.com/developer/api-keys). Keys start with `sk_` and are shown once. **Local sandbox requirement: `tokportal-mcp` 1.15.1 or later.** Version 1.15.0 exposes `dry_run` but does not forward the dry-run header. Use the remote endpoint or REST for simulations until your local server has been upgraded and restarted: ```bash npm install --global tokportal-mcp@1.15.1 ``` If your host launches the server through `npx`, change its arguments to `["-y", "tokportal-mcp@1.15.1"]` and restart it. If you cannot upgrade or verify the running version, use the remote endpoint or REST. See [Sandbox](https://developers.tokportal.com/sandbox) for the request and response contract. ## One-click install
Add to Cursor Add to VS Code Add to VS Code Insiders Add to Goose Add to claude.ai / ChatGPT
Pick your host below. Each snippet is copy-paste ready; replace `sk_...` with your own key where a key is required. Looking for a job-by-job recipe (create accounts, post 100 videos a day, ban webhooks…) for a specific host, including LangChain, CrewAI, Vercel AI SDK, Mastra, Copilot Studio, Dify, Flowise or Langflow? See [Use TokPortal from your agent →](https://developers.tokportal.com/agents) — 25 hosts × 12 jobs. ### Claude.ai and Claude Desktop Custom connector with OAuth — nothing to paste except the URL: 1. **Settings → Connectors → Add custom connector**. 2. URL: `https://app.tokportal.com/api/ext/mcp` 3. Sign in to TokPortal, choose **Full access** or **Read-only**, click **Authorize**. Works on claude.ai web, the Claude mobile apps and Claude Desktop. Full walkthrough: [Remote connector](https://developers.tokportal.com/mcp/remote). ### Claude Code Remote (OAuth, recommended): ```bash claude mcp add --transport http tokportal https://app.tokportal.com/api/ext/mcp ``` Then run `/mcp` inside Claude Code and authenticate in the browser. Local stdio alternative with an API key: ```bash claude mcp add tokportal -e TOKPORTAL_API_KEY=sk_... -- npx -y tokportal-mcp ``` Guide: [Claude Code social media workflows](https://developers.tokportal.com/use-cases/ai-agents/claude-code-social-media). ### Cursor Click **Add to Cursor** above, or add to `.cursor/mcp.json` (project) / `~/.cursor/mcp.json` (global): ```json { "mcpServers": { "tokportal": { "url": "https://app.tokportal.com/api/ext/mcp" } } } ``` Cursor opens the OAuth sign-in on first use. Prefer a key instead? Use the stdio form: ```json { "mcpServers": { "tokportal": { "command": "npx", "args": ["-y", "tokportal-mcp"], "env": { "TOKPORTAL_API_KEY": "sk_..." } } } } ``` Guide: [Cursor + TikTok via MCP](https://developers.tokportal.com/use-cases/ai-agents/cursor-mcp-tiktok). ### VS Code (GitHub Copilot agent mode) Click **Add to VS Code** above, or from a terminal: ```bash code --add-mcp '{"name":"tokportal","type":"http","url":"https://app.tokportal.com/api/ext/mcp"}' ``` Or in `.vscode/mcp.json` (project) / user `settings.json` under `"mcp"`: ```json { "servers": { "tokportal": { "type": "http", "url": "https://app.tokportal.com/api/ext/mcp" } } } ``` ### ChatGPT Custom connectors are available on ChatGPT plans that allow developer mode / custom MCP connectors: 1. **Settings → Connectors → Create** (or **Advanced → Developer mode → Create**). 2. Name: `TokPortal` · URL: `https://app.tokportal.com/api/ext/mcp` · Authentication: **OAuth**. 3. Save, then sign in to TokPortal when ChatGPT prompts you and choose the access level. Enable the connector per chat from the **+** menu. Read-only tools work in regular chat; write tools require the connector to be enabled in developer mode. ### OpenAI Codex CLI Add the remote server to `~/.codex/config.toml`: ```toml [mcp_servers.tokportal] url = "https://app.tokportal.com/api/ext/mcp" # either OAuth (run `codex mcp login tokportal` once) … # … or a static key from your environment: # bearer_token_env_var = "TOKPORTAL_API_KEY" ``` Then `codex mcp login tokportal` for the OAuth flow. Recent Codex builds also accept the one-liner `codex mcp add tokportal --url https://app.tokportal.com/api/ext/mcp`; the stdio form always works: ```bash codex mcp add tokportal --env TOKPORTAL_API_KEY=sk_... -- npx -y tokportal-mcp ``` ### Gemini CLI ```bash gemini mcp add --transport http tokportal https://app.tokportal.com/api/ext/mcp ``` Add `--header "Authorization: Bearer sk_..."` to skip OAuth. Equivalent `~/.gemini/settings.json`: ```json { "mcpServers": { "tokportal": { "httpUrl": "https://app.tokportal.com/api/ext/mcp", "headers": { "Authorization": "Bearer sk_..." } } } } ``` ### Windsurf `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "tokportal": { "serverUrl": "https://app.tokportal.com/api/ext/mcp" } } } ``` ### Cline Cline → **MCP Servers → Configure** (`cline_mcp_settings.json`): ```json { "mcpServers": { "tokportal": { "type": "streamableHttp", "url": "https://app.tokportal.com/api/ext/mcp", "headers": { "X-API-Key": "sk_..." } } } } ``` ### Goose Click **Add to Goose** above, or run `goose configure` → **Add Extension → Remote Extension (Streaming HTTP)** with URL `https://app.tokportal.com/api/ext/mcp`. Deeplink: ``` goose://extension?type=streamable_http&url=https%3A%2F%2Fapp.tokportal.com%2Fapi%2Fext%2Fmcp&id=tokportal&name=TokPortal ``` ### Zed `settings.json` → `context_servers`: ```json { "context_servers": { "tokportal": { "source": "custom", "command": "npx", "args": ["-y", "tokportal-mcp"], "env": { "TOKPORTAL_API_KEY": "sk_..." } } } } ``` ### JetBrains (IntelliJ, PyCharm, WebStorm…) **Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add**, command `npx`, arguments `-y tokportal-mcp`, environment `TOKPORTAL_API_KEY=sk_...`. Or paste the JSON: ```json { "mcpServers": { "tokportal": { "command": "npx", "args": ["-y", "tokportal-mcp"], "env": { "TOKPORTAL_API_KEY": "sk_..." } } } } ``` ### OpenClaw ```bash clawhub install tokportal ``` Then set `TOKPORTAL_API_KEY` in the skill config. Full guide: [OpenClaw](https://developers.tokportal.com/openclaw) · [Post to TikTok from OpenClaw](https://developers.tokportal.com/use-cases/ai-agents/openclaw-tiktok-posting). ### n8n (MCP Client node) Add an **MCP Client** node → transport **HTTP Streamable** → Endpoint `https://app.tokportal.com/api/ext/mcp` → Authentication **Bearer** with your `sk_...` key (or a Header credential `X-API-Key`). Guide: [n8n TikTok automation](https://developers.tokportal.com/use-cases/no-code/n8n-tiktok-automation). ### Perplexity **Settings → Connectors → Add connector → Custom** → URL `https://app.tokportal.com/api/ext/mcp` → OAuth. Choose Read-only if you only want research/analytics access. ### Any other MCP client - Streamable HTTP: `https://app.tokportal.com/api/ext/mcp` with OAuth 2.1 (discovery via `WWW-Authenticate` / `.well-known`) or `Authorization: Bearer sk_...` / `X-API-Key: sk_...`. - stdio: `npx -y tokportal-mcp` with `TOKPORTAL_API_KEY`. ### Verify it works Ask your assistant: > "What is my TokPortal credit balance? Use the TokPortal MCP tools." A working setup calls `tokportal_get_credit_balance` and answers with your balance. ## What you can do All 99 tools use the `tokportal_` prefix and are generated from the [public OpenAPI schema](https://developers.tokportal.com/api-reference), so the catalog is always in sync with the REST API. Tool discovery in your host is the authoritative list. | Category | Tools | Examples | | --------------------- | ----: | ------------------------------------------------------------------------------------------------------------------------------------------- | | Bundles (missions) | 10 | `create_bundle`, `create_bundles_bulk`, `publish_bundle`, `get_bundle_publish_readiness`, `add_video_slots` | | Videos | 15 | `configure_bundle_video`, `batch_configure_bundle_videos`, `import_bundle_videos_csv`, `publish_all_bundle_videos`, `finalize_bundle_video` | | Account configuration | 4 | `configure_bundle_account`, `finalize_bundle_account`, `request_bundle_account_corrections` | | Delivered accounts | 12 | `list_accounts`, `list_account_bans`, `create_account_edit_request`, `get_account_managed_subscription`, `reveal_account_credentials` | | Advanced warming | 5 | `generate_warming_terms`, `rewarm_account`, `list_account_warming_sessions` | | Analytics | 17 | `get_analytics_dashboard`, `get_analytics_series`, `list_account_video_analytics`, `create_analytics_report`, `export_analytics_videos` | | Comments | 7 | `create_comment_tasks`, `approve_comment_task`, `list_comment_task_verifications` | | Webhooks | 9 | `create_webhook_endpoint`, `list_webhook_deliveries`, `retry_webhook_delivery`, `test_webhook_endpoint` | | Uploads | 5 | `upload_video`, `upload_video_direct`, `upload_image_from_url` | | Credits & profile | 5 | `get_credit_balance`, `get_credit_costs`, `list_credit_transactions`, `get_current_user` | | Reference | 2 | `list_countries`, `list_platforms` | Try prompts like: - "Create a TikTok bundle in the US with 10 videos and advanced warming — generate 9 search terms for gaming content." - "Configure videos 1–5 on my latest bundle with these descriptions, one day apart starting March 15." - "Show analytics for all my US TikTok accounts sorted by engagement rate." - "List published bundles with videos pending review." - "Which of my accounts have an appeal pending?" ## Authentication model - **OAuth (remote)** — the host redirects you to TokPortal, you approve, and TokPortal mints a dedicated API key named **`Claude (MCP connector)`** (the same name is used for every OAuth host) that becomes the bearer token. Revoke it anytime in [Developer Portal → API Keys](https://app.tokportal.com/developer/api-keys) and the host loses access immediately. **Full** scope reads and writes; **Read-only** never spends credits. - **Bearer / header (remote)** — hosts without OAuth (n8n, Cline, scripts) send `Authorization: Bearer sk_...` or `X-API-Key: sk_...` on the same URL. - **stdio (local)** — `npx tokportal-mcp` reads `TOKPORTAL_API_KEY` and talks to `https://app.tokportal.com/api/ext` with `X-API-Key`. The key never leaves your machine except to TokPortal. - **Teams** — a teammate invited to a TokPortal Team connects the **team's workspace** (the owner's bundles, accounts and credits), never an empty personal one. The key lands in the owner's key list as `Claude (MCP connector) · teammate@example.com`. Connecting requires the team permission **API access**; Full access also requires **Spend credits**. See [Teams](https://developers.tokportal.com/mcp/remote#teams). Every call runs under your account, with the same rate limits (`X-RateLimit-*` headers, 429 + `Retry-After`) and audit logging as the REST API. Use separate keys per integration. ## Tool annotations Every tool ships MCP `annotations`: `title`, `readOnlyHint` (the **41** GET tools), `destructiveHint` (**23** tools), `idempotentHint` (**47** tools: GET / PUT / DELETE) and `openWorldHint` (**16** tools that put content or a profile change on a public platform: publishing, slot configuration carrying `auto_publish`, CSV import, corrections, public comments, profile edits, bundle creation, rewarm). Everything that stays inside your workspace — webhooks, uploads, analytics, credits, warming-term generation — is `openWorldHint: false`. Hosts that honor annotations can auto-approve read-only tools and prompt before destructive ones. > **INFO: `destructiveHint` changed meaning in 1.13.0** > > Up to 1.12.2 it was derived from the verb in the operation name, which flagged 14 tools — including reversible ones such as `reset_bundle_video` and `unschedule_bundle_video` — while leaving every credit-spending call unflagged. Since **1.13.0** the flag means one thing: **this call spends credits or releases a manager payout irreversibly**, plus the genuine cancel / delete / revoke operations. That is **23** tools. The twelve credit-spending operations that used to slip through unflagged now carry it; `reset_bundle_video` and `unschedule_bundle_video` no longer do. If your host auto-approves anything that is not `destructiveHint`, re-check that policy after upgrading. > > The full list: `create_bundle`, `create_bundles_bulk`, `publish_bundle`, `unpublish_bundle`, `add_video_slots`, `add_edit_slots`, `configure_bundle_video`, `batch_configure_bundle_videos`, `import_bundle_videos_csv`, `publish_bundle_video`, `publish_all_bundle_videos`, `finalize_bundle_account`, `finalize_bundle_video`, `create_account_edit_request`, `create_video_ad_code_request`, `create_comment_tasks`, `delete_comment_task`, `rewarm_account`, `reveal_account_credentials`, `retrieve_account_verification_code`, `reactivate_account_managed_subscription`, `cancel_account_managed_subscription`, `delete_webhook_endpoint` (all prefixed `tokportal_`). Tool names still follow a convention, so agents can classify by name as a cross-check — but the annotation is the authority, not the verb: - **Read-only** — every `tokportal_get_*` / `tokportal_list_*` / `tokportal_export_*` tool. Never spends credits; safe to auto-approve, and the only tools available on a Read-only OAuth connector. - **Write** — `configure_*`, `set_*`, `reset_*`, `unschedule_*`. These change your workspace but do not debit credits. - **Destructive / irreversible** — the 23 tools listed above. Every one of them either debits credits with no cancellation or refund path, releases a manager payout, or deletes something. Hosts should prompt a human before running them. ## Hard rules the schemas cannot express The server's `instructions` and the rewritten tool descriptions (69 of the 91 were rewritten in 1.13.0) now carry the rules an agent used to have to discover by being charged for them: - **Try before you buy.** On the remote MCP server, or local `tokportal-mcp` 1.15.1 or later, every non-`GET` tool accepts `dry_run: true`. It runs the same validation and the same pricing as the real call and stops before the first write: nothing created, nothing charged, no manager involved. The result has the same shape and the same errors, plus `credits_would_charge` with the real price. The recommended pattern is dry-run first, show the human what it costs, then repeat for real. Identifiers a dry run returns are synthetic and chain only into other dry-run calls; a real call refuses one with `DRY_RUN_ID_IN_LIVE_REQUEST`. See [Sandbox (dry run)](https://developers.tokportal.com/sandbox). - **No cancellation, no refund.** Credits are debited at bundle creation, not at publication. `tokportal_unpublish_bundle` does not refund. Confirm the total with a human before any create / add / publish / rewarm call. - **Advanced Niche Warming needs its flag.** `wants_advanced_warming: true` is mandatory alongside `advanced_warming_terms` or `advanced_warming_terms_count`; it is never inferred. Targets sent without it are refused with `ADVANCED_WARMING_FLAG_REQUIRED` instead of being charged and dropped. Send the term list **or** the count, never two quantities that disagree (`ADVANCED_WARMING_COUNT_MISMATCH`), and send distinct terms — anything removed by cleanup fails the call with `ADVANCED_WARMING_TERMS_REJECTED` rather than quietly shrinking what you buy. Advanced Niche Warming is the only warming TokPortal sells. - **Unknown arguments are refused over MCP.** Unrecognised top-level MCP arguments are no longer turned into query parameters, and the six full-replace endpoints (`create_bundle`, `create_bundles_bulk`, `configure_bundle_account`, `configure_bundle_video`, `batch_configure_bundle_videos`, `configure_bundle_warming_terms`) answer `UNKNOWN_FIELD` with a did-you-mean. REST callers instead get the names back in `meta.ignored_fields`. - **One bundle = one account**, max **3 videos per day per bundle**, and the earliest `target_publish_date` is today + 3 days while the account is still being created, today + 1 once it is delivered or when the bundle runs on an existing account. - **Delivered videos are approved automatically by default.** `auto_finalize_videos` defaults to `true` since 1.14.1: a delivery counts as final on arrival. Send `auto_finalize_videos: false` at creation (or via `tokportal_update_bundle` later) to review each delivery instead. The create responses echo the choice as `review_mode`, and add a one-off `review_mode_notice` when the caller left it to the default. - **Delivered work auto-finalizes \~72 hours after entering review**, regardless of `auto_finalize_videos`. Use `tokportal_finalize_bundle_video` or `tokportal_request_bundle_video_corrections` inside that window. - **Instagram slots require `instagram_content_type`; TikTok carousels require `tiktok_sound_url`.** For `carousel_images` and `profile_picture_url` use the upload response's `storage_path`, not `public_url` — videos are the opposite. - **Partial success is not failure.** `tokportal_batch_configure_bundle_videos` and `tokportal_import_bundle_videos_csv` answer 200/201 even when rows fail; read `configured` / `errors`. Since 1.13.0 the MCP result is marked `isError` only when **zero** items succeeded while errors are present, so a partially successful call is no longer indistinguishable from a total one. ## Safety: the 428 confirmation policy `tokportal_reveal_account_credentials` and `tokportal_retrieve_account_verification_code` can permanently detach an account from TokPortal management. They implement a two-step policy: 1. Call the tool **without `body`** → HTTP **428** with the full policy preview (`policy_version`, price in credits, consequences). Nothing is revealed or debited. 2. Show the complete policy to a human. Only after explicit confirmation, call again with `body.acknowledge_support_forfeit: true` and the exact `policy_version`. Never send `idempotency_key` to these tools. On `CREDENTIAL_REVEAL_QUOTE_CHANGED`, fetch a fresh preview and ask again. Ordinary account tools never return passwords, TokMail addresses, inbox content or codes. Pricing is likewise live: call `tokportal_get_credit_costs` right before quoting a charge (standard account setup 32 credits, Coverage 25 credits / 30 days after the included first period, Advanced Niche Warming 5 credits per target with a 15-credit minimum; contract allowances override these). On `BUNDLE_PRICING_CHANGED`, refetch and retry with a new idempotency key. Ban visibility: `tokportal_list_account_bans` is the only source of truth for ban state (`appeal_pending`, `appeal_accepted`, `appeal_refused`, `no_appeal_banned`, and the staff resolution). Agents must report these exactly and never infer a ban from other signals. See [Bans & Appeals](https://developers.tokportal.com/bans-and-appeals). ## Error diagnostics Failed calls return the original API payload plus diagnostics: ```json { "payload": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded." } }, "diagnostics": { "request_id": "req_...", "retry_after_seconds": 1, "rate_limit": { "limit": 120, "remaining": 0, "reset": 1779724800 } } } ``` Quote `request_id` when contacting support; respect `retry_after_seconds` before retrying. Correction tools accept both the nested body and flattened fields — these are equivalent: ```json {"id":"BUNDLE_ID","position":1,"body":{"comment":"Replace the sound","fields":{"sound":true}}} ``` ```json {"id":"BUNDLE_ID","position":1,"comment":"Replace the sound","fields":{"sound":true}} ``` ## Registry listings Listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=tokportal) as `com.tokportal/mcp` (auto-syncs to the VS Code / GitHub MCP registry), with a [Docker MCP Catalog](https://github.com/docker/mcp-registry/pull/4716) entry, an [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers/pull/12404) entry and a [Cline Marketplace](https://github.com/cline/mcp-marketplace/issues/2267) submission in review; a [Gemini CLI extension](https://github.com/tokportal/gemini-cli-extension) is available (`gemini extensions install https://github.com/tokportal/gemini-cli-extension`). Source and issues: [github.com/tokportal/tokportal-mcp](https://github.com/tokportal/tokportal-mcp) · npm: [tokportal-mcp](https://www.npmjs.com/package/tokportal-mcp). ## Troubleshooting | Symptom | Fix | | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Host shows "authentication required" / 401 loop | Finish the OAuth flow in the browser tab that opened; if none opened, re-add the server and run the host's auth command (`/mcp` in Claude Code, `codex mcp login tokportal`). For bearer setups check the key starts with `sk_` and is not revoked. | | Tools list is empty | The host cached an old session — remove and re-add the server, or restart the host. Both transports expose the same 99 tools. | | `npx tokportal-mcp` hangs on first run | It is downloading the package; run `npx -y tokportal-mcp` once in a terminal to warm the cache. Requires Node 18+. | | `INSUFFICIENT_CREDITS` | Top up at [app.tokportal.com/dashboard/credits](https://app.tokportal.com/dashboard/credits) or call `tokportal_get_credit_costs` to size the order. | | `RATE_LIMIT_EXCEEDED` | Wait `diagnostics.retry_after_seconds`; default limit is 120 requests/minute per key. | | Read-only connector cannot create bundles | Re-authorize with **Full access** (you can keep both connectors and pick per chat). | | Connector authenticates but reports 0 bundles, 0 accounts, 0 credits | You are a Team member whose connector was authorized before 2026-09-22, when the key was minted on your personal (empty) account. Remove the connector in your host and authorize it again: it now opens your team's workspace. | | Corporate proxy blocks `cursor://` / `vscode:` links | Use the JSON / CLI snippet for your host instead of the deeplink. | Need help? Email with the `request_id`.