Troubleshoot an MCP connection
Find the step that failed. Then check the project, server URL, sign-in, permissions, tool request, or returned file.
Connect AI is missing
- Confirm you are on the Cloud project details page.
- Check the selected organization and whether you have access to the project.
- Confirm the project is active and its dedicated Pro environment is ready.
- Check whether external MCP is enabled for the project. If it is not, use the built-in Chat or contact support about availability.
Changing the URL or port does not enable the feature. A project that no longer supports external MCP may still show AI connections. Use that panel to remove existing connections.
The server URL does not connect
Copy MCP server URL from the correct project again. Use the full value. Do not use the editor URL or homepage. Remove any extra spaces. Check that you replaced PROJECT_ID if you used an example.
Use remote Streamable HTTP with OAuth. A client hosted in the cloud cannot reach your computer’s localhost. If you open the server URL in a browser, you may see an authorization or protocol message. This address connects software; it is not an ordinary web page.
Registration or redirect is rejected
CADground supports OAuth client registration through dynamic registration, configured client identities, and HTTPS client metadata. After sign-in, the client receives a redirect at its callback address. That address must use HTTPS or literal HTTP loopback: 127.0.0.1 / [::1]. CADground does not currently support localhost callbacks or custom app URL schemes.
Check the exact error and the callback address documented by your client. In Codex, you can retry with explicit dynamic client registration (DCR). See the Codex setup guide. Cursor desktop may use an unsupported localhost callback. See the compatibility note.
Do not disable OAuth or paste browser cookies into the configuration. Do not change the callback in a generated sign-in URL by hand. It must match the callback the client registered.
Sign-in succeeds, but access is denied
- Confirm the email/account used during authorization has access to the project.
- Check the current membership, project role, and organization.
- Check whether the project was archived, paused, transferred, or changed plan.
- After fixing access, sign in through the client again or reconnect. An old token cannot restore access removed by a role change.
Read works, but camera movement or edits fail
- Open the project’s Connected clients list and inspect the displayed permission.
- Check your role. Viewer access cannot authorize write.
- Configure the client to request both
mcp:readandmcp:write. - If you are changing permissions, disconnect the old CADground connection. Then sign in through the client again.
- On the CADground permission screen, choose Read and write. Check the result in Connected clients.
Camera movement, focus, visibility, and selection all require write access. Some tools remain unavailable to external clients even with write access. Check the tool reference before reporting a permission error.
The tool says the project is busy
Wait for the current built-in AI task or external tool call to finish. To stop it, use the external client’s cancel control or Stop in the built-in Chat. Do not ask several agents to run scene operations at the same time.
Ask the external agent to make one tool call at a time. Before retrying, ask it to read the latest scene state. Repeated calls at the same time can keep the project busy.
The wrong or an empty scene is returned
- Verify the endpoint belongs to the intended project.
- Open the editor and select the intended Scene source.
- Wait for the source to load and any current task to finish.
- Ask the agent to read current workspace and scene state again before requesting a capture.
A picture can also look empty if the camera points away from the model, the source is hidden, or focus limits the view. Changing these settings requires write access. A read-only agent must report the problem; it cannot fix these settings.
Only a resource URI appears
Ask the client to read the returned resource through MCP. A cadground:// address is not a public URL. Generate a new picture if the address has expired. If the client cannot read this type of response, use a client that can. An agent must not claim to have inspected an image it cannot read.
For capture-size errors, reduce the requested image size. For example, 1920 × 1080 fits both the side-length and total-pixel limits.
A fitting operation times out
Save the error message. Check whether the scene changed before retrying. Select a smaller source region and start with simpler geometry. If the client stopped waiting too soon, use its documented setting to increase the timeout. A longer timeout does not fix unsupported inputs or a failed geometric fit.
What to send to support
Send the client name and version, public project URL or project ID, approximate time, and exact error. Include the permission level and the last setup step that worked. Say whether a read-only scene-state request works. Do not send passwords, session cookies, OAuth tokens, or model API keys. Contact support@cadground.ai.