MCP troubleshooting
Diagnose connection errors, denied tools, stale changes, and uncertain outcomes without repeating writes.
Start with one read-only test: ask the assistant to list your Prezly newsrooms, using a token with sites:read. Do not test the connection by creating, sending, publishing, or deleting something.
The client lists tools, but a read fails
Tool discovery is not a permission check. MCP can initialize and return its catalog before an API request validates the credential. Diagnose the failed read itself:
| Result | Next step |
|---|---|
authentication or HTTP 401 | Check the saved bearer credential, expiry/revocation, and the environment that launches the client. |
authorization or HTTP 403 | Check all required scopes, the token owner's permissions/newsroom access, and endpoint eligibility. |
not_found | Search/list again and reuse the returned identifier. The record may be deleted or unavailable to this connection. |
| Empty list | Check the selected account, newsroom, filters, and pagination; empty results can be valid. |
An error category alone cannot distinguish an invalid token from an expired or revoked one. Check its status in Prezly rather than guessing from the message.
Authentication fails
Check these connection details:
- URL:
https://mcp.prezly.com/mcp, including the/mcppath. - Transport: Streamable HTTP.
- Authentication: one
Authorizationheader withBearerfollowed by the personal token value, without surrounding quotes or extra whitespace. - Token: created in the intended Prezly account, still active, and not past its expiry.
If you replaced a token, check for an old saved header or duplicate server entry. Reconnect or restart the client after updating its settings. Never paste a token into chat or support logs to test it.
The client asks for OAuth sign-in
The hosted Prezly connection uses a fixed bearer token, not OAuth. In Claude's remote connector, choose No sign in (or None) and add the authorization request header. In other clients, choose their custom bearer/header option. A client that only supports OAuth cannot connect directly this way.
An environment variable is not being used
A Bearer token env var field takes the variable's name, such as PREZLY_API_TOKEN, not the token value. A terminal export affects processes launched from that environment; it does not update an app already running or launched elsewhere.
Check that the launching process has a non-empty value without printing it. Restart from that environment, or use the client's private static-header settings instead. Configure one method: remove a stale static authorization header if you use the bearer environment-variable field.
For Claude Code, the quoted ${PREZLY_API_TOKEN} reference in the setup command is expanded by the client when connecting. Keep the variable available when launching subsequent sessions.
A visible tool is denied even with write scopes
First inspect the token's selected permissions by clicking its name under Personal API tokens. Workflows often need multiple scopes: campaign-recipient reads need both campaigns:read and contacts:read, for example. Mutations also need reads for fresh-state checks.
Then check the owner's current Prezly permissions and newsroom access. A scope cannot grant a permission the owner lacks.
Finally, check the tools unavailable to personal tokens. For example, story duplication/translation/preview, campaign test sends/scheduling, and bulk contact deletion remain in the catalog but do not accept personal tokens. More scopes cannot resolve that restriction.
Do not retry an unchanged denial or switch to a more powerful credential automatically. If access needs to change, discuss the intended workflow with your administrator or Prezly Customer Success. To change token scopes, create a replacement and update the client.
A change returns precondition_failed
The current record did not match the supplied expected state. Another person or operation may have edited it since the assistant read it.
- Get the target again, or re-list the relevant settings to obtain a fresh digest.
- Compare that state with the intended action and check that the target is still correct.
- If the action still applies, submit it with those exact current values. Review again if the changed state affects what you approved.
Never substitute the desired status for expected_status, invent a timestamp, or blindly refresh preconditions just to make a write pass.
A change returns unknown_outcome
The operation may already have taken effect. MCP does not automatically repeat the mutation. Read before deciding whether to act again:
| Operation | How to reconcile |
|---|---|
| Created record | Search using the intended title/subject/headline and related newsroom or story. Check for an existing result before creating another. |
| Updated story, contact, pitch, or coverage | Get the same identifier and compare the fields with the intended change. |
| Campaign or pitch send | Get that same campaign/pitch and inspect delivery state. Do not resend to test whether the first request worked. |
| Recipient or tag change | Read the explicit selection and verify the intended membership. Search indexing and aggregate tag counts can lag. |
| Newsroom/configuration change | Get the newsroom and re-list the affected settings, domain, or membership. |
| Deletion | Re-read/search the target and inspect related records. Do not repeat a bulk deletion to resolve an uncertain result. |
Personal tokens cannot poll background jobs. A permitted write may receive an accepted response before job-status access is denied. MCP then reports an uncertain outcome; the denied completion check does not undo the accepted write.
If current reads still cannot establish the outcome, stop and ask for help. Keep the affected identifier and time of the attempt so the operation can be investigated.
The hosted endpoint returns 405, 406, or 415
Opening the URL in a browser is not an MCP connection test. This stateless endpoint accepts MCP POST requests, not GET or DELETE connection requests.
Client implementations need these protocol headers, in addition to authorization:
Content-Type: application/json
Accept: application/json, text/event-streamA 405 indicates an unsupported method, 406 an incompatible Accept header, and 415 an incompatible content type. Use a Streamable HTTP MCP client to handle initialization and tool calls; an ordinary JSON POST without the MCP protocol is not sufficient.
A request is rate-limited or times out
For rate_limited, pause and reduce request frequency. For a read timeout, narrow the query or request fewer records before retrying. Do not turn either into a blanket retry policy for writes.
A mutation timeout after dispatch is reported as unknown_outcome; follow the reconciliation steps above. A timeout during a precondition read, before dispatch, remains timeout. If you cannot tell whether a write started, establish current state first.
If taking a newsroom online returns capacity_exceeded, the account has no remaining live-site capacity. Decide whether to free capacity or change the account allowance. Re-reading and repeating the unchanged request will not fix it.
The token expired, was revoked, or was lost
Create a new token and replace the saved credential. Token values are shown only at creation and cannot be recovered. Revoked tokens cannot be reactivated. Verify a newsroom read with the replacement; if the old token is still active, revoke it after the replacement works.
See replace or revoke a token. Removing the MCP entry in a client does not revoke the token in Prezly.
Get help without sharing secrets
Record the client name/version, time of the attempt, tool name, safe error category or HTTP status, and whether it was a read or a change. Include record identifiers only in an appropriate private support channel. For a write, say whether you have reconciled the current state.
Exclude tokens, authorization headers, full tool arguments/results, contact details, unpublished content, and sensitive URLs from shared diagnostics. Describe the intended outcome in plain language so support can distinguish access problems from unsupported workflows.