Troubleshooting

Authentication errors (401 and 403)

A tool call fails with a 401 when the API key is missing, malformed, or revoked. This is the same 401 used by the REST API, see Errors. This section covers the Bearer key method (Claude Code, Cursor, n8n, the mcp-remote bridge); for an OAuth connector (ChatGPT, Claude.ai/Claude Desktop custom connectors), see the OAuth section below instead.

• Check the Authorization header in your client's config is exactly Bearer imma_live_... (or imma_test_...), with no extra whitespace or a duplicated Bearer prefix.
• Generate a fresh key from the dashboard if the old one was revoked or rotated.
• If a key was revoked mid session, the next tool call returns this error immediately; there is no separate "session expired" state to detect.
• Using an imma_test_ key against a live (non sandbox) account returns a 403 test_key_live_account, not a 401; swap in an imma_live_... key or point the call at a sandbox account instead.

OAuth connector errors (ChatGPT, Claude.ai / Claude Desktop)

These apply to a connector added through ChatGPT's Developer mode (a ChatGPT Plugins app) or Claude's Customize > Connectors > Add custom connector (or, for Team/Enterprise, Organization settings > Connectors), both of which authenticate with an OAuth login rather than a pasted key.

• Consent denied. You closed IMMA AI's consent screen or clicked deny instead of approving. Reopen the connector's settings and click Connect again to restart the login.
• Token revoked. Access was revoked from IMMA AI's /developers/mcp page, or you disconnected the connector on the client side. Either way, the next tool call fails until you reconnect and log in again.
• Wrong workspace chosen. IMMA AI's consent screen lets you pick which workspace to grant, and picking the wrong one connects the client to the wrong data. Disconnect the connector and reconnect, choosing the correct workspace this time.
• Authorization loop or redirect fails. The browser blocked a redirect or popups are disabled for the client's domain; allow popups and retry.

Tools missing from the tool list

If an expected tool, such as create_posts_batch or reply_comment, does not appear in your client's tool picker, it is almost always a scope issue, whether you connected with a Bearer key or an OAuth login: scopes decide which tools are even listed in tools/list, a tool you cannot use is not shown rather than shown and then rejected.

• Check which scope each tool needs on the Tools page.
• For a Bearer key, generate a new key with the scopes you need (posts:write, posts:read, accounts:read, accounts:write, analytics:read, inbox:write). For an OAuth connector, reconnect and confirm the requested scopes on IMMA AI's consent screen match what you expect.
• A read-only grant (posts:read, accounts:read, analytics:read) will only ever show read tools like list_accounts, get_post, list_posts and get_analytics.

A TikTok post is stuck in awaiting_approval

This is expected, not a bug. Every TikTok target created through MCP (create_post or create_posts_batch) requires the account owner to open the hosted approval link and choose a privacy option themselves; there is no MCP input that publishes directly. See Platform rules for why this rule exists and cannot be bypassed.

• Send the approval.url returned by the tool call to the account owner (commonly over Telegram).
• If the link expired, use POST /approvals/{id}/resend on the REST API (not yet exposed as its own MCP tool) to generate a new one.
• If you intended a draft instead of an approval link, use tiktok.mode: "inbox" so the post lands in the creator's TikTok inbox for them to finish and publish.

An agent tries to pick a TikTok privacy level itself

create_post and create_posts_batch do not accept privacy_level, disable_comment, disable_duet or disable_stitch from the agent for TikTok targets. If your agent's prompt or its own reasoning tries to set one, the value is silently ignored and the tool's result includes a warning explaining that privacy is chosen by the account owner on the approval page.

• This is enforced in packages/core, the same layer the REST API uses, so there is no MCP-only workaround.
• If you are building your own UI that already collects real consent from the account owner, use the REST API's consent flag directly instead of MCP, see Platform rules. MCP intentionally does not expose that flag, since an agent is not a UI that can show a human a preview.

Rate limited (429)

The MCP server shares the same rate limits as the REST API: 120 requests per minute per key, with a lower limit on post creation. See Rate limits.

• Back off using the wait time implied by the error rather than retrying immediately.
• When creating many posts at once, prefer create_posts_batch (up to 31 items) over calling create_post in a loop, both to stay under the rate limit and because batch validates and reports each item independently.

Media still processing

If upload_media returns status: "processing" and a post created shortly after references that media, the post itself is still created successfully; the affected target simply waits until the media becomes ready before it can publish. Call get_post to see the current target status, and get_post/get_analytics will reflect published once the media finishes processing and the post goes out.

Checking delivery status from MCP

The MCP equivalent of checking a post's live status is the same as the REST API: call get_post with the post_id returned by create_post or create_posts_batch. It returns per-target status, the live permalink once published, and a plain-language error for any target that failed. See get_post and the API reference for the underlying GET /v1/posts/{id} shape.