Troubleshoot Studio MCP
Resolve waiting connections, authentication and permission errors, lost credential delivery and interrupted operations.
Start in Settings → Connections and choose Check result. The displayed state records requests, not a permanent client session.
Connection states
| State | Next step |
|---|---|
| Waiting | Open the client and make a small read. Check its server URL and local credential variable. |
| Authenticated request received | Authentication reached Studio. Ask for site context if you have not yet made a useful read. |
| Last used | A request succeeded at that time. This can include initialization or tool discovery; it does not prove an edit occurred. |
| Authentication failed | Check the credential audience, URL, expiry, revocation and account status. |
| Insufficient permission | Use a permitted task or ask the owner for the specific missing access. |
| Connections are disabled | The owner can enable access unless server configuration controls it. |
| Account is inactive | Use a credential bound to an active permitted account. |
| Revoked or Expired | Remove the old credential from the client and create a replacement. |
An unknown or missing bearer value cannot reliably be attributed to a saved connection. The row may still show waiting while the client reports an authentication error.
The client is configured but cannot connect
Copy the exact Studio MCP endpoint, including any subdirectory. Use /_studio/mcp.php, not the visitor-facing /mcp.php or a REST Agent API URL. MCP and REST credentials have different audiences.
Confirm that the client supports Streamable HTTP and sends the bearer header. An environment variable must exist in the actual client process; a variable set in another terminal or after launch may not be available. Restart with the intended environment and make a small read.
If authentication headers disappear at the web server, check your host configuration. Do not bypass authentication or expose private draft directories to make the connection work. If Studio offers Finish private draft setup, complete that owner flow first.
The credential disappeared
Use Check result after a lost creation response. If Credentials ready to save contains an unclaimed delivery, choose Claim credential. Delivery is one-time and time-limited. If it was already claimed or is unavailable, revoke the credential and create a replacement. The retained creation result cannot reveal the secret again.
A request timed out or a review is stale
Inspect the retained operation before retrying. Reuse its identity for identical input and continue explicitly when instructed. Status reads do not advance it. If recovery is required, follow that operation’s recovery controls.
A stale review needs a new preparation against current source. Do not overwrite newer files to make an old review pass. For missing or truncated context, follow the returned ranges and read the remaining data before applying.
When requesting support, include the product and client versions, error code and operation ID if available. Exclude bearer credentials, secret preview links, provider keys and private customer data.
Found a mistake in these instructions? Open an issue.
Download VoxelSite