Connect your own agent (MCP)¶

N3XD supports the Model Context Protocol, so you can connect a coding agent such as Claude Code, Codex or Claude Desktop to a project. The agent can use the same commands as the UI. Its edits are recorded in your project history and appear in any browser tab where the project is open.

Your agent provides the language model, while N3XD stores the CAD state, runs the geometry kernel and returns information about the result. You can use a local model or a hosted one.

Connect to the hosted app¶

The endpoint is https://app.n3xd.io/mcp. For Claude Code:

claude mcp add --transport http n3xd https://app.n3xd.io/mcp

The first call opens a browser so you can sign in and approve the connection. The agent then receives a token with access to the projects available to your account. To revoke that token, sign the session out under Settings.

If you self-host N3XD, use the same endpoint with your own domain. The server is included in the app container, so you do not need to deploy anything else. An administrator enables it under AI Tool → MCP access and sets each user's command budget there.

Run it locally instead¶

For a standalone app without accounts, you can run the server over stdio and connect it to a local backend:

cd backend
make dev-backend                                    # the app, on :8000
N3XD_MCP_ENABLED=1 uv run python -m n3xd.mcp        # the shim, another shell

N3XD_MCP_APP_URL sets the app URL. It defaults to http://127.0.0.1:8000. For Claude Desktop, add an entry with the absolute path to app/backend so uv uses the correct environment:

{
  "mcpServers": {
    "n3xd": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/app/backend", "python", "-m", "n3xd.mcp"],
      "env": { "N3XD_MCP_ENABLED": "1", "N3XD_MCP_APP_URL": "http://127.0.0.1:8000" }
    }
  }
}

This transport does not send credentials, so it works only with a standalone app (auth.mode="none"). Calls to an app with user accounts are rejected. Use the hosted endpoint for those deployments.

A typical session¶

First, ask the agent to call get_command_catalog. It returns a short index of the commands your deployment supports, and the agent then calls describe_commands for the full payload schema of each command it is about to use. After that, it can follow a simple read, act and review cycle:

1. Read the model structure with get_model_tree. Use get_topology and find_entities to locate geometry, and get_sketch to inspect sketch elements.
2. Act with execute_command, the only tool that changes a project. It uses the same project lock and revision check as the UI, so a simultaneous browser edit is not overwritten. Several commands fit in one commands.batch call, which applies them as one revision.
3. Review the result with get_screenshot. By default, it returns front, top, right and isometric views, which can reveal mistakes hidden in a single view. Use measure and get_diagnostics to check dimensions and rebuild issues.

The tool reference lists everything and the command catalog documents the payloads.

What the agent can and cannot do¶

The agent can model parts and work with assemblies, parameters, configurations, simulations and slicing. It cannot delete projects, change sharing settings or access projects outside your account. Those commands are not in the catalog, and the server rejects command types that are not listed there.

N3XD records each command in the project history with an mcp: actor. You can see which changes came from the agent and undo them like any other edit. Each agent command stays its own revision, so the agent can also return to an earlier one with list_revisions and project.restore_revision.