# Troubleshooting the MCP server

Fixes for common problems with the Pozy MCP server, from sign-in loops and the wrong workspace to expired tokens, accounts that need reconnecting and tool limits.

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.

## Sign-in fails or loops

**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](https://pozy.ai/docs/mcp/connect)).

**The sign-in page says the account has no workspace yet.** Open the [Pozy dashboard](https://pozy.ai/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](https://pozy.ai/docs/build/tenant-keys) 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](https://pozy.ai/docs/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`](https://pozy.ai/docs/publishing/media) 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](https://pozy.ai/docs/getting-started/rate-limits): 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`](https://pozy.ai/docs/api/submitFeedback), or ask your assistant to file it.