TokPortal MCP Not Working? Fix Auth, Dry Runs and Posting Errors

Technical review: September 18, 2026, against the public documentation, current API schema and published npm package 1.15.1. Examples below are instructional templates, not customer results or a claim that a paid campaign was executed.

Your assistant says it connected, but no tools appear. Or a request says success while the video never becomes public. Those symptoms belong to different parts of the workflow, and reinstalling everything usually hides the useful evidence.

Start with the exact failing tool, its sanitized arguments and the returned error. This guide explains the documented failure modes and what to check next. It does not ask you to share a key, account password or private media link to diagnose a public integration pattern.

Confirm the remote URL is https://app.tokportal.com/api/ext/mcp. It is not the developer documentation URL or the REST API root. Complete the OAuth flow opened by the host, including workspace sign-in and the authorization screen.

In Claude Code, inspect the connection through /mcp. In Codex, run codex mcp login tokportal and inspect codex mcp list. If the login completes in one browser profile but your host never receives the callback, check the host’s reported authentication state before repeatedly adding new servers.

For a bearer or local API-key setup, verify that the key is present in the running process, belongs to the intended workspace and has not been revoked. Store it in the host’s private configuration or supported secret mechanism. A key pasted into a chat message is not automatically an environment variable.

Then retry a read-only call such as tokportal_get_credit_balance. Successful authentication does not require buying an account.

Check whether the host loaded the server, whether it is enabled for the conversation and whether it reports a transport error. A local stdio server needs an executable runtime and the correct configuration format for that host. The current package requires Node.js 20 or newer.

If you changed the local package version or configuration, restart the MCP server. A running process does not update itself because a JSON file changed. Refresh tool discovery using the host’s controls; a stale session can keep an old catalog.

The setup page includes working configuration shapes and a searchable snapshot of the 91 management tools in npm 1.15.1. Use it to find names, then read your connected server’s actual schemas. Do not assume a newer AI-generation endpoint appears in an older local management package.

A stdio process may stay open waiting for protocol input when launched in a terminal. That alone does not prove it is hung. Inspect the host’s connection diagnostics and use a real MCP client for the smoke test.

A read-only OAuth connector can read balances and accounts but cannot create bundles. Re-authorize with the intended write access when you are ready to perform that work. Keep a read-only connection for reporting if that is all the task needs.

Management dry runs still enforce authentication, scopes and business validation. dry_run: true is not a permission bypass. A simulated creation can fail for the same validation reasons as a live one.

Inspect the error before changing access. An insufficient balance, invalid country and missing required field are different problems. Increasing permissions will not repair a misspelled field or a schedule in the past.

Check the transport and running version first. Local tokportal-mcp 1.15.0 must not be used for simulations: the documented issue is that it exposes the argument without forwarding the required header. Use the remote endpoint or update the local launch arguments to ["-y", "tokportal-mcp@1.15.1"] and restart.

Send the boolean dry_run: true at the top level of the tool arguments. For REST management calls, the equivalent is X-TokPortal-Dry-Run: true. Do not put the flag in the JSON request body and assume it will be recognized.

A successful management simulation reports dry_run: true, zero credits_charged and the actual credits_would_charge. If a supposed preview appears to have executed, stop further writes and reconcile the bundle and credit transactions. Do not “test again” by repeating a paid operation.

Synthetic IDs start with 00000000-0000-4000-8000-. They work only in further dry-run operations and are not stored objects you can read with a normal GET. A live operation rejects them with DRY_RUN_ID_IN_LIVE_REQUEST. Recreate the approved resource live once, then use that real ID.

These rules cover the management sandbox. The newer AI endpoints use a separate USD wallet, quotes and permissions; they do not advertise the legacy dry-run contract. Inspect the actual capability before assuming a generation request is a free test.

Compare the request with the connected tool’s schema. For ordinary JSON operations, API fields belong inside body; path arguments such as id and position belong outside it. MCP rejects unknown arguments instead of guessing what you meant.

Two common placement errors have specific fixes. On batch configuration, move auto_publish out of each video and put it beside videos at the root of body. For an explicit publishing end date, use the supported metadata PATCH operation; the ordinary configure call derives its end from the start date.

Read ignored_fields and warnings after successful calls. Sending tiktok_sound_url to an Instagram slot does not select Instagram audio. Sending a TikTok link_in_bio through account configuration does not establish a working profile link.

When correcting a PUT configuration, send the complete intended configuration. Do not repair a typo by accidentally clearing the other fields you omitted from the retry.

Use the returned earliest_allowed and min_days_ahead values. Dates are checked in UTC. New accounts still being created need at least three days of lead time; existing or delivered accounts need at least one.

A bundle permits at most three videos targeting one day. Spread the affected slots across valid days instead of submitting the same invalid batch repeatedly. Existing non-cancelled slots count toward the cap, so inspect the bundle’s current schedule as well as the new rows.

The configured date starts a two-day publishing window. If work sat in setup until its date became stale, publication can move the schedule forward and report adjusted videos. Read the returned schedule; do not treat the earlier plan in your spreadsheet as the current truth.

A swipeable Instagram carousel needs video_type: "carousel" plus instagram_content_type: "post". With instagram_content_type: "reel", the images become a fixed-photo video. Both can be valid requests while only one matches your intent.

Instagram Stories use video_type: "story", exactly one image or video, and no description or instagram_content_type. Music uses instagram_audio_name. The Instagram MCP tutorial walks through all three formats.

For uploaded media, videos use public_url; carousel and profile images use storage_path. Check the actual upload response rather than manufacturing a path. A real file accessible from your own browser may still require credentials the download service does not have.

Read the batch’s configured, errors and per-item results. Partial success can still return HTTP 200 or 201, and MCP only marks certain fully failed batches as errors. The outer success indicator is not a count of completed work.

Repair the failed positions and retry those. If auto_publish was enabled, also read its published, blockers and error information. Configuration can succeed while publication remains blocked.

Finally, distinguish submitted work from delivery. A published bundle is not itself a public TikTok post. Look for the actual delivered URL or appropriate evidence. Stories use evidence_screenshot. If a review or correction is needed, act within the documented window.

For RATE_LIMIT_EXCEEDED, respect the returned retry delay, including diagnostics.retry_after_seconds where provided. Dry runs consume rate limits too. Repeated simulations are not a free polling mechanism.

For BUNDLE_PRICING_CHANGED, refresh the quote and inspect the changed cost before approving a new purchase attempt. The management guide specifies a fresh idempotency key for the newly priced request. Do not silently accept a higher quote because an earlier one was approved.

For a network timeout after an ordinary supported paid write, reconcile whether it already succeeded, and preserve the logical operation’s idempotency key when retrying. This is different from intentionally changing the order. Some secret-bearing operations do not accept replay keys; check the specific schema.

If a credential-reveal request returns a 428 policy preview, do not automatically acknowledge it to make the error disappear. That workflow can permanently detach account management. Normal account creation, posting and reporting do not require password reveal.

Once the failure is understood, resume from the last confirmed state. Do not recreate everything because the assistant cannot remember a bundle ID. Keep your campaign ledger outside the chat and make every step report the identifiers it used.

Start with one TikTok account, one Instagram pilot or one existing-account distribution batch. Expanding a verified workflow is much easier than diagnosing a hundred ambiguous jobs at once.

For support, provide the sanitized report through the official contact in the MCP documentation. The request ID is usually more useful than a screenshot of an assistant saying “something went wrong.”

MCP practical guides: installation, GitHub and tools · create TikTok accounts · Instagram accounts and publishing · TikTok distribution · fix MCP errors.