TokPortal MCP Server

One-click install

Cursor, VS Code and Goose open their installation dialog. Then sign in to TokPortal to authorize access. For Claude, Codex and ChatGPT, follow the custom connection steps below.

Connect in a few steps

TokPortal does not need to appear in your AI app’s plugin directory. Add it as a custom remote MCP server using this URL:

https://app.tokportal.com/api/ext/mcp

1. Choose your app below and open its custom MCP connection settings.
2. Paste the URL, name the server TokPortal, and use OAuth to sign in to your TokPortal workspace.
3. After authorizing, enable the server in your conversation. Ask it to read your credit balance without changing anything.

A prompt can help explain setup, but it cannot install or authorize a connector by itself. Never paste an API key or your social-account password into a chat.

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.

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

Custom connector with OAuth — nothing to paste except the URL:

1. Open Customize → Connectors → Add → Custom → Web. Some versions call this 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.

Set it up from Claude web or Desktop; mobile installation can vary. Team and Enterprise workspaces may require an administrator to add the connector first. 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 → Apps → Create custom app (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 app in the conversation’s tools menu. Availability and administrator approval depend on your ChatGPT plan and workspace.

Codex

In the desktop app, open Settings → MCP servers → Add server. Name it tokportal, choose Streamable HTTP, and paste https://app.tokportal.com/api/ext/mcp. Save, restart the server if prompted, and choose Authenticate to sign in. The desktop app, CLI and IDE share MCP configuration.

For the CLI or IDE, run:

codex mcp add tokportal --url https://app.tokportal.com/api/ext/mcp
codex mcp login tokportal

The configuration alternatives below remain available.

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

Tools use the tokportal_ prefix and are generated from the public OpenAPI schema, so discover the current catalog in your connected host. Older local packages may not expose newer Inbox operations; use the remote server or update the package.

For the account Inbox, use the connection and Inbox guide. It covers received comments and replies, available moderation actions, keyword filters, Instagram conversations and comment-to-DM, with settings, history and result webhooks. API replies and messaging currently have no credit debit; provider limits, permissions, Coverage and messaging windows still apply. Paid human Seeding is separate.

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

Connection troubleshooting

• TokPortal is not in the directory: use a custom server with the exact URL above. A directory listing is optional.
• The AI only describes the setup: finish adding and authorizing the server in the host settings, enable its tools in the chat, then ask for a read-only balance check.
• No Add custom connector option: check your host version and workspace administrator permissions. Codex CLI, Claude Code and Cursor provide direct remote-server configuration alternatives.
• Read works but write fails: review the TokPortal access granted to the connector. Read-only access does not permit a write, including a simulated write. Never grant more permission silently.
• Social-account capability is unavailable: connecting your AI and connecting a social account are different steps. Follow account connection and Inbox status; permissions, Coverage and messaging windows still apply.

Host instructions checked

Reviewed October 20, 2026 against OpenAI MCP setup, Claude custom connectors, Claude Code, Cursor, VS Code, and Gemini CLI. Host menu labels and workspace permissions can vary.