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

Get an API key (only needed for stdio / bearer setups) from the Developer Portal. 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:

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 for the request and response contract.

One-click install

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 → — 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.

Claude Code

Remote (OAuth, recommended):

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:

claude mcp add tokportal -e TOKPORTAL_API_KEY=sk_... -- npx -y tokportal-mcp

Guide: Claude Code social media workflows.

Cursor

Click Add to Cursor above, or add to .cursor/mcp.json (project) / ~/.cursor/mcp.json (global):

{
  "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:

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

Guide: Cursor + TikTok via MCP.

VS Code (GitHub Copilot agent mode)

Click Add to VS Code above, or from a terminal:

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

{
  "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:

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

codex mcp add tokportal --env TOKPORTAL_API_KEY=sk_... -- npx -y tokportal-mcp

Gemini CLI

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:

{
  "mcpServers": {
    "tokportal": {
      "httpUrl": "https://app.tokportal.com/api/ext/mcp",
      "headers": { "Authorization": "Bearer sk_..." }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "tokportal": {
      "serverUrl": "https://app.tokportal.com/api/ext/mcp"
    }
  }
}

Cline

Cline → MCP Servers → Configure (cline_mcp_settings.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:

{
  "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:

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

OpenClaw

clawhub install tokportal

Then set TOKPORTAL_API_KEY in the skill config. Full guide: OpenClaw · Post to TikTok from OpenClaw.

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.

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, so the catalog is always in sync with the REST API. Tool discovery in your host is the authoritative list.

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 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.

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).
• 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.

Error diagnostics

Failed calls return the original API payload plus diagnostics:

{
  "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:

{"id":"BUNDLE_ID","position":1,"body":{"comment":"Replace the sound","fields":{"sound":true}}}

{"id":"BUNDLE_ID","position":1,"comment":"Replace the sound","fields":{"sound":true}}

Registry listings

Listed on the official MCP Registry as com.tokportal/mcp (auto-syncs to the VS Code / GitHub MCP registry), with a Docker MCP Catalog entry, an awesome-mcp-servers entry and a Cline Marketplace submission in review; a Gemini CLI extension is available (gemini extensions install https://github.com/tokportal/gemini-cli-extension). Source and issues: github.com/tokportal/tokportal-mcp · npm: tokportal-mcp.

Troubleshooting

Need help? Email team@tokportal.com with the request_id.