Troubleshooting the MCP server

Start every investigation with one question to your assistant: "Which Pozy workspace am I connected to, and can you make changes?" The answer comes from whoami and rules out half the problems below.

The browser opens, you sign in, and the client still says it is not connected. Remove the server or connector from the client, add it again and sign in once more. Several clients cache a failed attempt and keep showing it until the entry is re-added.

"Couldn't register" or a similar registration error. Client registration is open to any MCP client, so this is almost always a passing network problem. Remove and re-add the server. If it keeps failing, fall back to an API key in the Authorization header (see Connect a client).

The sign-in page says the account has no workspace yet. Open the Pozy dashboard once to finish creating your workspace, then sign in from the client again.

#401 Unauthorized

The server did not accept the credential.

Using	Check
OAuth	The grant was revoked, or the refresh token expired after 30 days unused. Remove and re-add the server to sign in fresh.
API key	The key is active in Developers → API keys, has not expired, and was pasted without spaces or quotes.
A key in a JSON config	The client may be sending the literal text `$POZY_API_KEY`. Paste the key itself, or use the client's secrets mechanism.

#The assistant sees the wrong workspace or no accounts

Wrong workspace. An OAuth grant belongs to the workspace you chose at sign-in. Revoke the client under Settings → Connected apps and connect again, picking the right one. An API key always belongs to the workspace it was created in.
"No connected accounts match." Sign-in worked, but this workspace has no accounts, or the key is profile-scoped to profiles that have none. Connect an account in the dashboard, or ask the assistant to run connect_account.
Some accounts are missing. A profile-scoped key only sees its profiles. Check the key's scope, or use list_profiles to see what the connection can reach.

#The assistant cannot make changes

The tool answers with read_only_key or insufficient_permissions.

The client asked only for the read scope, or you approved it read-only. Reconnect and approve write access.
Your role in the workspace is viewer, which is always read-only. Ask an owner or admin to change your role.
An API key with permission: read cannot write. Create a read-write key if the agent must act.
resource_group_disabled means the key has that area switched off, for example ads. Create a key with the group enabled.

#A post failed

Ask "Why did my last post fail?" The assistant calls get_post and reads the error for each platform. From the terminal: curl https://api.pozy.ai/v1/posts/<postId> -H "Authorization: Bearer $POZY_API_KEY".

The usual causes:

Error says	Do this
The account needs reconnecting, or its token expired	Reconnect it (ask the assistant for a `connect_account` link with the account id), then retry with `retry_post`
Media type or size not accepted	Check the platform's limits in Platforms; re-encode or resize, then post again
Missing title	YouTube needs a `title`
Rate limited by the platform	Wait and retry; platforms cap posts per day on some account types

dry_run: true on create_post catches most of these before anything is published.

#It picked the wrong account

Name the account: "post from @acme". When more than one account is connected on a platform, the post tools refuse to guess and return the candidates, so a good assistant asks you. If yours did not, say which one and ask it to use account_ids.

#Tools are missing or the client is slow

After editing a config file, nothing changed. Quit and reopen the client completely. Most clients read MCP settings at startup only.
The client shows fewer tools than expected. Pozy offers 27 tools. Clients that cap their tool list still have everything through search_tools and call_tool.
Long answers get cut. Tool answers stop at 60,000 characters. Ask for a smaller limit, a shorter date range or one platform at a time.
A file upload operation fails through call_tool. It only sends JSON. Use the REST API, for example curl -F, for multipart uploads such as CSV import. To get a local image or video online first, upload it with POST /v1/media/presign and use the URL it returns.
Timeouts on big analytics ranges. Split the range into months.

#Rate limits

MCP traffic counts toward your workspace's API rate limit: 30 requests a minute on the free plan, 120 with a payment method and 300 on enterprise. An assistant that loops over many accounts can hit it; the error tells it how many seconds to wait.

#Still stuck

Email support@pozy.ai with the client you use, the time it happened and, if you have it, the request id from the error. You can also send it from the API with POST /v1/feedback, or ask your assistant to file it.

#Sign-in fails or loops