tokportal/tokportal-mcp

TokPortal is the managed social infrastructure API: real TikTok and Instagram brand accounts created, warmed and operated by human account managers in 16+ countries, exposed as a REST API and an MCP server. Run geo-sharding across markets without connecting every social account through OAuth. YouTube bundle creation is not available through this API.
**Upgrade before using the sandbox:** local tokportal-mcp requires **1.15.1 or newer** for dry_run. Version 1.15.0 advertised the argument but did not send the sandbox header, so a preview could execute a real operation. Update your local server or use the remote connector.
Docs https://developers.tokportal.com · API base https://app.tokportal.com/api/ext · OpenAPI https://developers.tokportal.com/openapi.json · MCP remote https://app.tokportal.com/api/ext/mcp · Get an API key https://app.tokportal.com/developer/api-keys?utm_source=npm&utm_medium=readme&utm_campaign=tokportal-mcp · llms.txt https://developers.tokportal.com/llms.txt
---
tokportal-mcp is the official Model Context Protocol server for the TokPortal API. Its 99 core tools remain available to Claude, Cursor, VS Code, Windsurf, Codex, Gemini CLI and other MCP clients. When AI is enabled for your workspace, seven additional curated tools cover model discovery, quoted generation, media management and the separate AI USD wallet. Model-specific schemas are fetched on demand, not exposed as hundreds of tools.
Two ways to use it:
| Mode | Transport | When to use |
| --- | --- | --- |
| **Local** (npx tokportal-mcp) | stdio | Desktop clients, local agents, file uploads from disk |
| **Remote** (https://app.tokportal.com/api/ext/mcp) | Streamable HTTP | Hosted agents, no install; same tool catalogue |
Requires Node.js 20 or newer. The local server runs on it directly. Get an API key at https://app.tokportal.com/developer/api-keys?utm_source=npm&utm_medium=readme&utm_campaign=tokportal-mcp (format sk_ + 64 hex chars).
30-second quickstart
The server speaks MCP over stdio. Point any MCP client at it and ask, for example:
> "Read the available countries, credit prices and my balance. Preview a TikTok account-only bundle in the USA with dry_run: true. Show me the immediate and recurring costs, and wait for my GO before any live purchase."
The preview calls tokportal_create_bundle with { "dry_run": true, "body": { "bundle_type": "account_only", "platform": "tiktok", "country": "USA" } }. It validates the request and returns credits_would_charge with credits_charged: 0, without creating work. Creation in live mode is charged immediately. Preview IDs are synthetic and must never be reused in live requests. After GO, create the real resources and use their live IDs. See the sandbox contract.
Programmatic smoke test with the MCP SDK:
AI generation (staged availability)
AI discovery calls authenticated GET /ai/status. If unavailable, only the existing catalogue is shown; no provider fallback or automatic payment is attempted. Local AI support requires 1.16.0 or newer and server-side availability. Installing this package does not enable generation, grant spending permissions or activate billing. Version 1.15.1 retains the existing account-management tools without AI discovery. Remote availability is controlled server-side.
Generation requires body: { quote_id, max_cost_usd } and idempotency_key. Reuse the same key after an uncertain response. Quotes expire within 15 minutes; use the returned expiry. The AI dollar wallet is independent of account-management credits. AI tools do not accept the legacy dry_run contract; use the quote operation, which does not start paid provider work. Cancellation is best effort, not a refund guarantee. Creation does not publish: review the returned assets, then use existing TokPortal scheduling tools.