Model Context Protocol (MCP)

Connect your AI tools to TokPortal using MCP

The Model Context Protocol (MCP) is a standard for connecting Large Language Models (LLMs) to platforms like TokPortal. Once connected, your AI assistant can create bundles, configure accounts and videos, track analytics, and manage your entire TokPortal workflow — all through natural language.

TIP: Using claude.ai (web or mobile)? Skip the config file. Add TokPortal as a one-click Remote Connector with OAuth login — no API key to paste. This page covers the local npm package for Cursor, Claude Desktop, Windsurf and agents.

Quick Setup

Step 1: Get an API key

Generate an API key from the Developer Portal. Your key starts with sk_ and is shown only once.

Step 2: Configure your AI tool

Add TokPortal MCP to Cursor

Or manually add to .cursor/mcp.json:

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

Claude Desktop

Add to your claude_desktop_config.json:

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

Windsurf / Other MCP clients

Use the same configuration format. The MCP server runs via npx tokportal-mcp — no installation required.

Step 3: Verify the connection

After setup, verify the connection by asking your AI assistant:

"What is my TokPortal credit balance? Use MCP tools."

If connected, the assistant will call the get_credit_balance tool and return your current balance.

Available Tools

The TokPortal MCP server is generated from the public OpenAPI schema. The full generated surface currently exposes 78 operations, but most workflows only need a small subset: auth, credits, bundles, videos, webhooks, uploads, and analytics.

Error Diagnostics

When an API request fails, MCP tool output includes 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
    }
  }
}

Use request_id when contacting support. Use retry_after_seconds before retrying a rate-limited tool call.

Tool	Description
tokportal_get_current_user	Get authenticated user
tokportal_list_countries	List available countries
tokportal_list_platforms	List available platforms
tokportal_get_credit_costs	Get credit pricing
tokportal_get_credit_balance	Get credit balance
tokportal_list_credit_transactions	List credit transactions
tokportal_list_bundles	List bundles
tokportal_create_bundle	Create a bundle
tokportal_create_bundles_bulk	Create bundles in bulk
tokportal_get_bundle	Get a bundle
tokportal_publish_bundle	Publish a bundle
tokportal_get_bundle_publish_readiness	Check bundle publish readiness
tokportal_unpublish_bundle	Unpublish a bundle
tokportal_add_video_slots	Add video slots to a bundle
tokportal_add_edit_slots	Add edit slots to a bundle
tokportal_get_bundle_account	Get bundle account configuration
tokportal_configure_bundle_account	Configure bundle account profile
tokportal_get_bundle_video	Get video slot configuration
tokportal_configure_bundle_video	Configure a video slot
tokportal_patch_bundle_video	Patch video references
tokportal_batch_configure_bundle_videos	Configure video slots in bulk
tokportal_publish_all_bundle_videos	Publish all configured videos on an active bundle
tokportal_list_accounts	List delivered accounts
tokportal_get_account	Get a delivered account
tokportal_list_account_bundles	List bundles for a delivered account
tokportal_retrieve_account_verification_code	Retrieve latest account verification code
tokportal_reveal_account_credentials	Reveal delivered account credentials
tokportal_get_account_edit_request	Get active account edit request
tokportal_create_account_edit_request	Request profile edits for a delivered account
tokportal_list_webhook_endpoints	List webhook endpoints
tokportal_create_webhook_endpoint	Create a webhook endpoint
tokportal_get_webhook_endpoint	Get a webhook endpoint
tokportal_update_webhook_endpoint	Update a webhook endpoint
tokportal_delete_webhook_endpoint	Delete a webhook endpoint
tokportal_list_webhook_deliveries	List webhook deliveries
tokportal_test_webhook_endpoint	Send a test webhook
tokportal_get_analytics_dashboard	Get analytics dashboard
tokportal_get_analytics_series	Get analytics time series
tokportal_get_analytics_account	Get account analytics drilldown
tokportal_get_account_analytics	Get account analytics compatibility view
tokportal_list_account_video_analytics	List post analytics for an account
tokportal_get_video_analytics	Get single video analytics
tokportal_get_comment_pulse	Get comment pulse analytics
tokportal_list_analytics_account_comments	List comments for an account post
tokportal_list_comment_tasks	List comment tasks
tokportal_create_comment_tasks	Create comment tasks
tokportal_get_comment_task	Get a comment task
tokportal_delete_comment_task	Delete a comment task
tokportal_approve_comment_task	Approve a manually confirmed comment task
tokportal_dispute_comment_task	Dispute a manually confirmed comment task
tokportal_list_comment_task_verifications	List comment task verification events

Usage Examples

Once connected, you can use natural language to interact with TokPortal:

Create a campaign:

"Create a TikTok bundle in the US with 10 videos and niche warming for gaming content"

Configure videos:

"Configure videos 1-5 on my latest bundle with these descriptions and schedule them one day apart starting March 15"

Check analytics:

"Show me the analytics for all my US TikTok accounts, sorted by engagement rate"

Manage workflow:

"List all my published bundles and show me which ones have videos pending review"

Get verification codes:

"Get the verification code for my account @mybrand_us"

npm Package

The MCP server is published as tokportal-mcp on npm.

npx tokportal-mcp

No installation required — npx downloads and runs it automatically.

Security

• Your API key is stored locally in your MCP configuration file and is never sent anywhere except to the TokPortal API.
• The MCP server runs locally on your machine as a stdio process.
• All communication with TokPortal uses HTTPS.
• We recommend using separate API keys for MCP and other integrations.
• You can revoke API keys at any time from the Developer Portal.