Skip to content
CADground Documentation
Documentation menu

Connect Codex

Add your project as a remote MCP server. Allow access in CADground, then check the active scene.

2 min readUpdated

Before you start

Complete the MCP availability checks. Copy your project’s MCP server URL. These steps use the Codex command-line interface (CLI) to show the exact settings. Run setup and sign-in in the same user environment as your Codex client. Windows and WSL installations can have different settings.

1. Register the server

Open a terminal where Codex is installed. Replace the quoted example URL with your copied project URL, then run:

codex mcp add cadground --url "https://cadground.ai/api/mcp/projects/PROJECT_ID"

The name cadground identifies this connection locally. Use a different name for another project. Configuration examples and CLI behavior are described in OpenAI’s MCP documentation.

2. Sign in and choose access

codex mcp login cadground --scopes mcp:read,mcp:write

Follow the browser link and sign in to CADground. Check the project, then choose Read only or Read and write. The command requests both permissions. You can allow write access only if your project role permits it. Requesting write access does not grant it automatically.

If automatic client registration fails, retry using Codex’s explicit registration option:

codex mcp login cadground --scopes mcp:read,mcp:write --oauth-client-registration dcr

3. Check the connection

codex mcp list

Start or reopen the Codex session that will use this connection. In the CLI, /mcp shows server status. A listed server confirms that it was configured. You still need a successful tool call to confirm access.

Use the cadground MCP server. Read the current workspace and scene source. List the objects. Take a picture without moving cameras or editing geometry. Tell me which scene the tools returned.

Check that the result matches the scene open in your CADground project. If it belongs to another project, stop. Correct the server URL before making edits. If the result is only a resource address, ask Codex to read that MCP resource.

Long geometry operations

A geometry tool can take longer than Codex waits for a reply. To allow more time, set a longer tool timeout in the server’s Codex configuration:

[mcp_servers.cadground]
url = "https://cadground.ai/api/mcp/projects/PROJECT_ID"
tool_timeout_sec = 600

Edit the existing entry. Do not add a duplicate. A longer timeout does not fix a busy project, missing write permission, or an unavailable tool. Start with one small region and check the reported error.

Choose the permissions for your task

For read-only work, ask for a measurement between clear points. For camera movement or geometry edits, allow read and write. State which changes the agent may make.

Inspect the antenna selected in our task. Use several camera views. Measure the visible front face. Report its direction relative to the scene axes. Do not assume that scene +Y is true north. Leave geometry unchanged.

This request needs write access because it moves the camera. It does not change geometry. For sign-in, permission, or connection errors, see MCP troubleshooting.