Civil 3D MCP Server
An MCP server that lets AI assistants run task-specific C# directly inside Autodesk Civil 3D through three tools.
Execute C# with full Civil 3D API access to create, edit, or delete drawing objects and return JSON results.
Run intended read-only C# queries for listing objects, inspecting properties, or analyzing surfaces without saving changes.
Save completed drawing changes via
saveDrawing, guarded byexpectedDrawingidentity checks.Use optional idempotency keys to reconcile uncertain write outcomes.
Browse, search, and read a library of documented C# skill templates for Civil 3D tasks.
Search already-loaded Civil 3D public API metadata with
api_lookup.Work with auto-imported Civil 3D namespaces and standard globals like
Document,CivilDoc,Database,Transaction, andEditor.
Provides integration with Autodesk Civil 3D by executing C# code inside the Civil 3D environment, allowing AI to query and modify drawings, surfaces, alignments, COGO points, and other Civil 3D objects through the full Civil 3D API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Civil 3D MCP Server List all surfaces in the current drawing."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Civil 3D MCP Server — Dynamic Roslyn Fork
An MCP server that enables AI assistants to write and execute C# code directly inside Autodesk Civil 3D. Instead of a large set of fixed tools, the AI generates task-specific code that runs with Civil 3D API access.
Project Scope and Lineage
This fork keeps the dynamic Roslyn/C# execution model and a deliberately small public surface of three MCP tools. Its current compatibility baseline is Autodesk Civil 3D 2025, with local work focused on reliability, safety, measurable efficiency, and reusable Civil 3D skills. Other Civil 3D versions can be added later through separately verified compatibility work.
The project is derived from barbosaihan/civil3d-mcp. SantosSjba/mcp-to-c3d was evaluated for selected, test-backed ideas, while Sacred-G/Civil3D-mcp was used only as an architectural reference. See PROVENANCE.md for the detailed attribution and licensing boundaries.
This independent project is not affiliated with or endorsed by Autodesk. Autodesk assemblies and other proprietary Civil 3D files are not included.
Related MCP server: Civil 3D MCP Server
Architecture
+-------------------------+--------+-------------------------+--------+-------------------------+
| AI Assistant | <----> | MCP server | <----> | Civil 3D plugin |
| (Codex, clients) | stdio | 3 public MCP tools | TCP | Dynamic Roslyn engine |
+-------------------------+--------+-------------------------+--------+-------------------------+
| |
v v
+-------------------------+--------+-------------------------+
| Skills Library |--------| C# execution |
| (*.skill.md) |--------| Civil 3D API |
+-------------------------+--------+-------------------------+Exactly 3 Public MCP Tools
Tool | Purpose | Safety |
| Execute C# code with write access; optional clean-drawing check and backup before, save after, and a receipt of what happened | ⚠️ Modifies drawing |
| Run intended read-only C# without committing the host transaction | Trusted code only; not a side-effect sandbox |
| Browse/search/read code skill templates; | ✅ Metadata only |
The tools carry MCP annotations so a client can tell them apart: civil3d_skills is read-only, civil3d_execute is a non-idempotent write, and none reaches outside the local Civil 3D session. civil3d_query is deliberately not advertised as read-only: its transaction is rolled back, but it still runs arbitrary code.
Working order for assistants
How an assistant works with the server (status first, identifying the target drawing, sending a write with its safety inputs, reading the receipt, what to do after an error or a timeout) is written in one place: docs/USAGE.md. The other sections of this README describe what the server does; they do not restate that order.
The server hands the guide to the assistant itself, so nothing else has to be installed:
its first part is sent as the MCP server
instructionswhen a client connects;civil3d_skillswithaction: "guide"returns the same part, and withtopic(drawing,writing,errors,csharp) the details;the descriptions of
civil3d_queryandcivil3d_executename the first step and point to the guide, because not every client shows server instructions;the
statusreply ends with aguideline that says the same.
The guide covers only how this server works. Where backups are kept, how many attempts are allowed and how results are reported are the user's own rules and are not part of it.
How It Works
AI reads a skill → Gets a documented C# code template
AI adapts the code → Fills in parameters, combines patterns
AI sends code → Via
civil3d_executeorcivil3d_queryRoslyn compiles + runs → Inside Civil 3D with full API access
Results return as JSON → Back to the AI
Example Interaction
User: "What surfaces are in my drawing?"
AI: Uses civil3d_query with:
var surfaces = new List<object>();
foreach (ObjectId id in CivilDoc.GetSurfaceIds()) {
var s = Transaction.GetObject(id, OpenMode.ForRead) as TinSurface;
surfaces.Add(new { s.Name, s.Layer });
}
return surfaces;
Result: [{ "Name": "EG", "Layer": "C-TOPO-EG" }, ...]Skills Library
civil3d_skills also supports action: "api_lookup" for a bounded, read-only search of public type and member names/signatures from already-loaded allowlisted Civil 3D host assemblies. It does not load assemblies, run C# code, or access the active drawing. Supply a query and optionally an assembly, namespace prefix, and result limit. The best match comes first: the type named exactly by a query word, then a member named exactly so, then types that start with the word, before the remaining matches in alphabetical order. Besides the core assemblies the search reads the pressure-pipe and data-shortcut assemblies when Civil 3D has loaded them. action: "status" reports versions and running instances, and action: "guide" returns the working order for assistants.
Skills are documented C# code templates in skills/:
The catalog contains 41 skills. Six focused engineering recipes cover design profiles from explicit PVIs, individual section views, existing native material quantities, sampled TIN elevation comparison, data-reference state and corridor target audits. Use civil3d_skills to search/get a recipe, bind project-approved inputs and run it through the existing query/execute tools. Recipes marked run_by_name (40 of 41, all except replace_alignment_with_fixed_primitives, whose input is a free-form table) can run directly with skill and params instead of code, so the template is not sent back and forth, and get with view: "card" returns just their parameters with type, default and row fields; see running by name. For earthwork quantities, create_tin_volume_surface keeps a TIN volume surface between two surfaces (with cut/fill factors) in the drawing, and bounded_volumes reads its cut, fill and net volumes inside labelled closed polylines, for example one per structure. For horizontal layout, create_alignment_from_pis builds an alignment from PI coordinates with an arc or clothoid-arc-clothoid group at each PI, and create_offset_alignments adds dynamic offset alignments, such as edges of pavement, to an existing alignment. For cross sections, create_sample_lines places perpendicular sample lines at explicit stations, an interval or geometry points with checked vertices and station-based names, create_section_view_group creates one native section view group (draft grid or template sheet placement, band sources, view names), shift_section_view_elevations moves the views' elevation window, keeping each view's height or setting a sheet height below the lowest ground point, plan_section_sheet_fit reads the template layouts to show which sheet fits the views' width and elevation height, rename_sample_lines_by_station renames sample lines after their actual station with a configurable name format, previewing the names first, and survey_row_station_candidates reads hand-measured survey rows across the road (AutoCAD points, survey blocks, also inside xrefs, or COGO points) and lists one candidate station per row, also in dense junctions, with an optional filter on the surveyor's point codes and a review flag for doubtful rows, ready for create_sample_lines; on request it also returns the measured height of each point and the distance, height difference and slope between neighbouring points of a row, read from the geometry or from a block attribute of a survey drawn flat. For looking at a drawing, plot_view_image returns a picture of the model space or of a sheet as the plot engine draws it (extents or a window), and plot_layouts_to_pdf checks the page setup of sheets (device, paper size, plot style table, scale) and plots each one to its own PDF file. See the recipe guide for inputs, limits and upstream attribution.
Search also recognizes specific Hungarian/English task aliases and workflow tags, with accent/hyphen normalization: for example hossz-szelvény, keresztszelvény, cross section, közmű and mennyiség. List/search show write scope, the tested Civil version and a short validation summary. Offline compilation, live execution, saved readback and reopen remain separate evidence; missing evidence stays unknown. Aliases are included in get rather than every page. See the catalogue contract for response fields, legacy defaults, compact discovery and metadata authoring.
Skill search matches every supplied word across names, categories, descriptions and parameter metadata, in any order. Underscores and whitespace are equivalent: surface volume and volume surface both find surface_volume. When no skill contains every word, the skills closest to the query are returned instead and the reply carries partial: true with matchedWords and queryWords, so one extra or unknown word does not hide the catalog; closeness is the total length of the matched words, and words shorter than three letters do not count toward it. A query with no normalized word, or with no matching word at all, returns no matches. Successful tool results use compact JSON with the same fields and values.
Proven: offline compilation for all six and scoped Civil 3D 2025 synthetic-fixture checks for profiles, section views, surface comparison and native quantities. Reference reporting was checked only on local/empty objects, and target auditing on an empty corridor. Populated DREF/target cases, populated section-view bands, section-view saved-file reopen/print quality and general model/standards correctness remain Unverified. The separate create_surface_profile_view recipe is proven offline; live authoring and saving remain Unverified. Full evidence boundaries are in the guide and PROJECT_STATUS.md.
skills/
├── surfaces/ # Surface operations
├── alignments/ # Alignment + station/offset
├── profiles/ # Profile inventory + controlled profile creation
├── corridors/ # Corridor summaries + target audit
├── sections/ # Inventory, controlled views + native material quantities
├── references/ # Bounded data-reference state audit
├── pipe_networks/ # Gravity pipe-network QC
├── points/ # COGO points
├── geometry/ # Lines, polylines, text
├── drawing/ # Drawing info
└── workflows/ # Complex multi-object operationsScript Globals
Code executed via civil3d_execute or civil3d_query has access to:
Global | Type | Description |
|
| Active AutoCAD document |
|
| Active Civil 3D document |
|
| Document database |
|
| Active transaction |
|
| Document editor |
| function | Marks a PNG or JPEG file as a picture to return; see pictures |
| function | A fresh file path in the plugin's image folder for a plot or export ( |
Return values
Return a value to get it back as JSON. Supported: primitives, strings, Guid, dates and times (ISO 8601 text), anonymous objects and classes or records declared in the script (public properties and fields, camelCase names), arrays, lists and any other sequence including LINQ queries without .ToList(), tuples (as arrays; element names do not exist at run time), Dictionary<string, …>, ObjectId, Handle, Point2d/3d and Vector2d/3d. Enums return as their names ("Tangent"; combined flags as "A, B"). DBObject instances are refused.
Replies are kept small for the assistant that reads them. A double is rounded to 10 significant digits, and its whole part is never rounded: 650123.456789012 returns as 650123.4568, 0.30000000000000004 as 0.3. That is a tenth of a millimetre on a seven-digit coordinate and far finer than any angle or slope in a drawing; a script that needs every digit returns the number as text. float and decimal values are returned as they are.
A collection with more than 1000 items keeps its first 1000, and the reply is then wrapped as {"result": …, "truncated": [{"path": "$.items", "returned": 1000, "total": 5234}]}; total is null for a lazy sequence whose length is unknown. A lazy sequence runs the script's own code while the result is read, still inside the transaction and under the same loop checkpoints and timeout; an exception there is reported with its type and path.
The whole result is limited to 40000 characters of JSON, which is roughly 10000 to 16000 tokens. A longer result is shortened instead of refused: the largest list loses items from its end, then the longest text its tail, and only when neither is left a table keyed by name its last entries. Lists also stop taking items once about 10000 values were converted. Each such cut is listed under truncated with "reason": "size", for example {"path": "$.rows", "returned": 412, "total": 900, "reason": "size"}, or with returnedCharacters and totalCharacters for a text. Ask for the rest with a narrower script (a name, a station range, Skip and Take). Depth stays limited to 8.
NaN and Infinity have no JSON form. Each one becomes null, and the reply is wrapped as {"result": …, "nonFinite": {"count": 3, "paths": ["$.rows[4].elevation", …]}} with the first 20 paths, so one undefined number no longer discards the whole result. truncated and nonFinite appear side by side when both apply; a result with neither keeps its plain shape.
Pictures
A script can hand a picture to the assistant: it writes a PNG or JPEG file, for example by plotting to a raster device, and returns ImageFile(path) anywhere in its result. The plugin reads the file and sends it next to the JSON result; the MCP server passes it on as an image block after the text. In the JSON the picture is replaced by a reference in the order of the image blocks, {"image": 1, "mimeType": "image/png", "bytes": 48213, "width": 1600, "height": 1280}.
One result carries at most 4 pictures, 2 MB each and 4 MB together; more, a file of another type or a missing file fails the call with a message instead of dropping the picture silently. NewImagePath() gives a path in %LOCALAPPDATA%\Civil3dMcpRoslyn\images; the plugin removes files older than a day from that folder when it hands out a new path, because a script cannot delete files. The plot_view_image recipe uses both. Whether a client shows image blocks of a tool result to its model depends on the client. An older plugin does not know ImageFile, so such a script fails there at compilation; the plugin lists images among its features in the status action.
All Civil 3D namespaces are auto-imported. A few type names exist in two of them and would otherwise be rejected as ambiguous (CS0104); they have a default meaning:
Bare name | Means | Other type, by full name |
|
|
|
|
|
|
|
|
|
|
|
|
A full name, the script's own using X = …; alias or a type the script declares still wins. Other duplicated names (for example Table) stay ambiguous and need the full name.
Committing the civil3d_execute transaction changes the open drawing but does not by itself write the DWG file to disk. A write must name its target as expectedDrawing (full Database.Filename and FingerprintGuid); the plugin checks that identity immediately before Civil API access. saveDrawing: true also saves the completed change. How the target is identified and in which order a write is sent is in the usage guide. The plugin saves only after the script transaction and document lock are closed; scripts must not call Database.SaveAs or queue QSAVE themselves. The save request uses a separate 10-minute default timeout and is never retried automatically. A drawing that is open read-only is refused with CIVIL3D.DRAWING_READ_ONLY (outcome: "not_started") before the script runs, instead of committing the change in memory and failing only at the save.
Safety switches, receipt and journal for writes
civil3d_execute can do the checks around a write itself, so the assistant does not need separate calls for them. This section says what each input does; when to use them, and what to do with the receipt and the journal after an error, is in the usage guide (topics writing and errors).
Input | Effect |
| Runs only when the drawing has no unsaved changes ( |
| Copies the saved DWG file to a time-stamped copy before the script runs, for example |
| Absolute folder for that copy. Default: |
| One line about the change. It is shown on the Civil 3D command line as |
Every write that reached the drawing returns a receipt next to its result. The result stays alone in the first text block; the receipt is a second text block:
{"receipt": {"drawing": {"databaseFilename": "C:\\Projects\\Plan.dwg", "fingerprintGuid": "{…}"},
"dbmodBefore": 0, "dbmodAfter": 1, "committed": true, "saved": true,
"fileLastWriteUtc": "2026-11-11T09:30:00.0000000+00:00", "fileBytes": 1843200,
"backupPath": "C:\\Users\\me\\AppData\\Local\\Civil3dMcpRoslyn\\backups\\Plan.20261111-103000.dwg"}}committed says whether the change is in the open drawing, saved whether this call wrote the file, and the file fields describe the file on disk after the call. A refused or failed write carries the same block (and structuredContent.receipt), so a failed save is visibly a committed, unsaved change. Queries have no receipt.
The plugin also appends one line per write request to a local journal, %LOCALAPPDATA%\Civil3dMcpRoslyn\journal\<year>-<month>.jsonl (override with CIVIL3D_MCP_JOURNAL_DIR in the Civil 3D process): time, Civil 3D session, drawing, description, SHA-256 and size of the code, success or error code, committed, saved, backup path, DBMOD before and after, duration and plugin commit. It never contains the code or the result. A journal that cannot be written does not change the outcome of the write.
A plugin from before these switches would ignore them silently. The server therefore asks the plugin for its feature list first and refuses with CIVIL3D.PLUGIN_UPDATE_REQUIRED (not_started) when requireClean, backup or backupDirectory cannot be honoured.
Time limit and cancelling
A script may run for 120 seconds. timeoutSeconds (1–1800) on civil3d_query and civil3d_execute changes the limit for that one call; use it for a known long operation such as a large rebuild. At the limit the script is stopped at its next loop iteration and the transaction is rolled back. A script that reaches no loop cannot be stopped midway, but when it returns after the limit its result is discarded and nothing is committed either. In both cases the reply is CIVIL3D.TIMEOUT with outcome: "reported_error": the drawing is unchanged, and the same write can be sent again with a larger timeoutSeconds.
The MCP server waits longer than the plugin's limit, so that this definite answer arrives instead of an uncertain one: at least 30 seconds beyond the script limit, and CIVIL3D_COMMAND_TIMEOUT (or CIVIL3D_SAVE_TIMEOUT when the drawing is saved) extended by whatever timeoutSeconds adds to the default 120 seconds. The MCP client's own tool-call timeout is separate and must also allow the time.
When the client cancels a tool call (for example the user presses Stop), the server closes its connection to the plugin. A request that has not started is dropped; a running script stops at its next loop iteration, or has its result discarded when it returns, and is rolled back. The call reports CIVIL3D.CANCELLED: not_started if it was never sent, otherwise unknown, because a write that had already reached commit stays committed. What the assistant does after a time limit or an unknown outcome is in the usage guide (topic errors).
Setup
Where everything lives
On a Windows computer the MCP keeps everything in one standard folder per user, %LOCALAPPDATA%\Civil3dMcpRoslyn (C:\Users\<user>\AppData\Local\Civil3dMcpRoslyn). It needs no administrator rights, and every computer gets the same layout:
Folder | Contents |
| The installed server that MCP clients start: |
| Plugin bundles replaced by |
| Drawing copies made by |
| The write journal. |
| Picture files of |
| Records of the running Civil 3D instances. |
The Civil 3D plugin goes where Autodesk loads add-ins from: %APPDATA%\Autodesk\ApplicationPlugins\Civil3dMcpPlugin.bundle. The source folder (the git clone) is needed only to build and can be anywhere; the standard place is %USERPROFILE%\source\repos\civil3d-mcp-roslyn, the default folder of Windows development tools, which OneDrive does not sync. MCP clients never start the server from the source folder.
1. Build
Needs Node.js 22 or later, the .NET 8 SDK and git.
git clone https://github.com/nezolder/civil3d-mcp-roslyn.git "$env:USERPROFILE\source\repos\civil3d-mcp-roslyn"
cd "$env:USERPROFILE\source\repos\civil3d-mcp-roslyn"
npm ci
npm run build
# Copy the Civil 3D reference DLLs to C_References/ first (see C_References/README.md)
dotnet build plugin/Civil3dMcpPlugin -c Release2. Install
npm run install:server # copies the server to %LOCALAPPDATA%\Civil3dMcpRoslyn\server
npm run install:plugin # close every Civil 3D firstinstall:server ends by printing the settings for the clients below with the full path filled in. Civil 3D asks once at its next start whether to load the new, unsigned plugin. Details: Installing a build.
3. Connect the AI clients
JSON settings do not expand %LOCALAPPDATA%, so they name the full path. Restart the client after a change.
Claude Desktop (claude_desktop_config.json) and other JSON clients:
{
"mcpServers": {
"civil3d": {
"command": "C:\\Program Files\\nodejs\\node.exe",
"args": ["C:\\Users\\<user>\\AppData\\Local\\Civil3dMcpRoslyn\\server\\build\\index.js"]
}
}
}Claude Code:
claude mcp add civil3d --scope user -- node "$env:LOCALAPPDATA\Civil3dMcpRoslyn\server\build\index.js"Codex (~/.codex/config.toml):
[mcp_servers.civil3d]
command = 'C:\Program Files\nodejs\node.exe'
args = ['C:\Users\<user>\AppData\Local\Civil3dMcpRoslyn\server\build\index.js']4. Update
git pull
npm ci # only when package-lock.json changed
npm run build
npm run install:server # close the AI clients that use the MCP first
dotnet build plugin/Civil3dMcpPlugin -c Release
npm run install:plugin # close every Civil 3D firstThen start the AI clients and Civil 3D again. The client settings stay as they are.
Loading by hand during development
NETLOAD → select Civil3dMcpPlugin.dll
C3DMCPSTATUS → verify running
C3DMCPRESET → release an operation that is stuck while Civil 3D is idleTo try a server build without installing it, a client can start <source folder>\build\index.js directly; switch it back to the installed copy afterwards.
Versions and installing a build
Both halves say which source state they were built from. npm run build writes the commit and build time next to the compiled server, and the plugin build stamps them into the DLL. The server reports itself to MCP clients as 1.0.0+<short commit>.
civil3d_skills with action: "status" returns the server's commit, build time and skills folder, and for every running Civil 3D instance its instanceId, process, port, plugin commit and build time, the active drawing, whether an operation is running, and buildMatchesServer. Its warnings list names an instance whose plugin was built from another commit, a plugin too old to report its build, and builds made with uncommitted changes. The status reads health replies only and runs no command in Civil 3D. A mismatch is also logged once per Civil 3D session.
A build made where git is unavailable reports unknown. Pass the commit in when needed: CIVIL3D_MCP_COMMIT=<full hash> for npm run build, -p:Civil3dMcpCommit=<full hash> for dotnet build.
Installing a build
The development folder is a poor place to run from: switching a branch there changes the live skill catalogue at once, and npm run build empties build/ while it compiles. Two commands copy a finished build to where it runs:
npm run install:server # or: node scripts/install.mjs --server --target <folder>
npm run install:plugin # or: node scripts/install.mjs --pluginServer: copies
build/,skills/and only the packages needed at run time to%LOCALAPPDATA%\Civil3dMcpRoslyn\server, checks that the copy loads on its own, then swaps it in. The copy it replaces is kept asserver.previous. Close the clients that use it first: a running server keeps its old code until it restarts, and if Windows still holds a file in the folder the command stops and leaves the installed copy as it was. At the end it prints the client settings that start<that folder>\build\index.js.Plugin: copies the Release build into
%APPDATA%\Autodesk\ApplicationPlugins\Civil3dMcpPlugin.bundle, which every Civil 3D loads at start. It refuses while a running Civil 3D holds the installed DLL, first copies the installed bundle to%LOCALAPPDATA%\Civil3dMcpRoslyn\backup\<date-time>\, and verifies each copied file by hash. Afterwards it keeps the newest 3 of the backup folders it made and removes the older ones;--keep-backups <n>changes the number and0keeps all. Folders with other names are never touched. Civil 3D asks once at its next start whether to load the new, unsigned file.
Neither command changes an MCP client's configuration.
Environment Variables
Variable | Default | Description |
|
| Plugin host. The plugin listens on IPv4 loopback only. |
| unset | Optional fixed-port override. When omitted, local instance discovery is active and the plugin prefers port 8080. |
|
| With |
|
| TCP connection timeout (ms) |
|
| Timeout for private health and drawing-identity probes (ms) |
|
| Base wait for one plugin reply (ms). For scripts the wait is never shorter than the script limit plus 30 s; see time limit. |
|
| Plugin process: |
|
| Base wait for execute requests with |
|
| Plugin process: default folder for |
|
| Plugin process: folder of the write journal (absolute path). |
|
| Plugin process: folder for the files of |
| from git | Build time only: commit recorded by |
|
| Log level |
Command/save timeouts must resolve to a positive integer of at most 2147483647 milliseconds; invalid or empty settings use the listed defaults. Log levels are debug, info, warn and error, ignoring case and surrounding whitespace; unrecognized values use info. Invalid timeout warnings omit the supplied value.
Civil requests run as correlated modal commands. The existing serialization gate stays held until the script has disposed its resources and that command ends; completing the script body alone does not release it. A request that has not started within 15 seconds is abandoned, and its late token cannot execute another request. The legacy backend is never selected automatically after a timeout. Every loop in a script checks for cancellation at the start of each iteration, so a runaway loop stops at the script time limit (120 seconds unless the call sets timeoutSeconds) and its transaction is rolled back. When the MCP server closes the connection, for example after a client cancel or its own command timeout, a request that has not started is dropped and a running script stops at its next loop iteration, also without committing. Long single Civil API calls cannot be interrupted, but a script that returns after its limit, or after the client is gone, is not committed. A script that uses await is rejected before compiling, because awaiting on the Civil 3D main thread can deadlock the application.
Multiple Civil 3D instances
Each loaded plugin session publishes a small local endpoint record containing only an opaque instance ID, process ID, program name, port, and start time. It contains no drawing name or project data. The first Civil 3D instance prefers port 8080; another instance automatically uses a free localhost port.
A record normally disappears when its Civil 3D session ends. One left behind by a crash or a killed process is removed by the next plugin session that starts, and until then the MCP server skips records whose process no longer exists, so stale records do not slow down every call. Windows may reuse the process ID of a closed Civil 3D for another program; a record whose ID now belongs to a different program is removed as well. A session that the caller names with instanceId is always probed.
If exactly one instance is available, existing calls work as before. With multiple instances, expectedDrawing is used to find the matching active drawing before the requested C# reaches any plugin. An unguarded bootstrap query fails closed with CIVIL3D.INSTANCE_SELECTION_REQUIRED and reports the live candidates; retry it with the optional instanceId on the existing tool. The final plugin-side drawing guard still checks the path and fingerprint immediately before Civil API access. No fourth public MCP tool is added.
Choosing between instances runs no command in any of them. Each plugin remembers which drawing is active, refreshed on the main thread whenever Civil 3D is idle (at most four times a second) and after each MCP operation, and repeats it in its health reply (activeDrawingKnown, activeDrawing). The server matches expectedDrawing against those replies, so the other instances, for example ones another assistant is working in, are not interrupted. Only an instance that cannot say yet (an older plugin, or one that has not been idle since it started) is still asked with the internal identity command. If the remembered drawing is a moment out of date, the call is refused by the drawing guard as not_started; it never reaches the wrong drawing. civil3d_skills with action: "status" lists the instances and their drawings.
Leave CIVIL3D_PORT unset for automatic selection. Setting it deliberately pins the MCP server to that one port for compatibility or diagnostics.
Benchmarking
The phase 2A host-independent recorder, the phase 2A.1 opt-in internal live trace contract, and the phase 2A.2 read-only live runner are documented in benchmark/README.md. None adds an MCP tool, queue, or retry; the 2A.2 runner can invoke only its fixed read-only query when explicitly started.
Structured errors (phase 2B.1)
civil3d_query and civil3d_execute keep their existing text error content and isError: true, while also returning structuredContent with schema civil3d-mcp-error/v1. The stable error fields are code, category, message, source, outcome, and retryable. A command timeout or a connection loss after sending has outcome: "unknown" and retryable: false; the server never retries it automatically. The plugin's own script time limit (CIVIL3D.TIMEOUT) is different: it is raised before any commit, so its outcome is reported_error and the drawing is unchanged. Successful responses and the three-tool public surface are unchanged.
An operation whose Civil command has not started within 15 seconds returns CIVIL3D.COMMAND_CONTEXT_TIMEOUT with outcome: "not_started" and retryable: false. A subsequently arriving abandoned token performs no drawing work. This deadline limits admission, not execution: started work retains the serialized gate until the selected backend's host completion, and an uncertain write must still be reconciled rather than repeated. The targeted completion checks do not establish that every possible hang is eliminated.
The timeout message says what is known about the cause: a command or prompt was waiting for input, the command was handed over but did not begin, or Civil 3D did not become idle at all (a command is still running, or its window needs one click).
A query runs through its own internal command (C3DMCPREAD), registered without an Undo marker, so that queries do not pile up in the user's Undo list; a write runs through C3DMCPRUN and stays one Undo step. A query that opens an object for write can still mark the drawing as modified (DBMOD), although its change is rolled back; queries should only read.
If an operation stays marked as running although Civil 3D sits idle at its command line, the person at the computer can type C3DMCPRESET in Civil 3D. It releases a request that never started (nothing ran) or one whose script had finished but whose command end Civil 3D never reported (CIVIL3D.COMMAND_FAILED; committed in the receipt says whether the change went in). It cannot interrupt a running script, because no command starts while one runs.
Compile a single C# code body offline
The skill test runner can check an individual UTF-8 .cs code body against locally supplied Civil 3D 2025 assemblies:
dotnet run --project tests/skills/Civil3dMcp.SkillTests.csproj --configuration Release -- --code (Resolve-Path ./probe.cs).PathThe file contains a method body that uses the provided Document, CivilDoc, Database, Transaction and Editor parameters. This checks compilation diagnostics only; it does not execute the code or connect to Civil 3D. Exit codes are 0 for success, 1 for compilation errors, and 2 for invalid arguments, a missing input file or missing Autodesk references. Calling the runner without arguments still checks every skill template and its input tests. A successful compile is not live behavior evidence.
Private TCP framing (phase 2C.1)
Each localhost TCP connection carries one UTF-8 JSON-RPC request and one response. Each JSON body is followed by LF and is limited to 8 MiB, measured as UTF-8 bytes without the LF. The Node client still accepts the previous plugin's unframed response when that complete JSON body is followed by an orderly connection close. Oversized requests are rejected before they are written; oversized or malformed responses and interrupted connections produce non-retryable structured transport errors. If execution completed but the plugin could not return an oversized result, the reported outcome is unknown.
Operation audit logging and write idempotency (phase 2I.1 / 2I.2)
At the default info log level, each accepted civil3d_query and civil3d_execute operation emits one bounded stderr audit event. It contains a new opaque operation ID, tool name, SHA-256 and UTF-8 byte length of the C# source, success/error status, and elapsed milliseconds; errors add only stable code/category/source/outcome fields. The audit event never contains caller code, description, drawing identity, result, or error message. It exists only where the client keeps the server's stderr; the lasting record of writes is the plugin's journal, which does hold the drawing path and the description.
civil3d_execute also accepts an optional opaque idempotencyKey (1–128 ASCII letters, digits, ., _, :, -). In one plugin session it binds the key to the UTF-8 C# SHA-256, normalized expectedDrawing identity, and saveDrawing choice. A duplicate is rejected as in-progress, conflicting, or already committed; committed entries retain no result and callers must reconcile with a read-only query. A save failure occurs after the in-memory write commit, so its key is kept as completed to prevent an accidental duplicate modification. The session keeps at most 256 completed keys, evicting the oldest deterministically. This adds neither persistence nor automatic retry or exactly-once semantics.
Security
Before a script runs, the plugin refuses it (CIVIL3D.SANDBOX_VIOLATION) when it uses:
Processes (
System.Diagnostics.Process,ProcessStartInfo)Deleting files or folders (
File.Delete,Directory.Delete,FileInfo.Delete,DirectoryInfo.Delete)Network requests (
System.Net.Http,System.Net.Sockets,WebClient,WebRequest)The registry (
Microsoft.Win32.Registry,RegistryKey)Loading assemblies (
Assembly.Load…,AssemblyLoadContext,AppDomain.CreateDomain)Native calls (
DllImport,Marshal,NativeLibrary)Ending the process (
Environment.Exit,Environment.FailFast)
All Civil 3D API operations are allowed.
The check reads what the compiler resolved, not the script text. A comment, a string or a name that only looks similar (process.StartStation, styleRegistry.Add) is therefore not refused, and a short name behind a using line (File.Delete) is. The error names the type or member and its script line.
This guard is defense in depth, not a trust boundary: a script can still reach these operations indirectly, for example through reflection. Both code tools receive mutable Civil 3D and AutoCAD API objects; civil3d_query skips the host's transaction commit but cannot guarantee that arbitrary dynamic C# is side-effect-free. Run only trusted, approval-gated code. Loopback TCP prevents remote network access but does not authenticate other local processes.
License
MIT
Available Tools
3 toolscivil3d_executeA
Execute C# code in Civil 3D with write access. The code runs inside a committed transaction. Available globals: Document, CivilDoc, Database, Transaction, Editor. All Civil 3D namespaces are auto-imported. Return a value to get results back as JSON. Use this for operations that MODIFY the drawing (create, edit, delete objects). expectedDrawing must come from a prior read-only identity query. To persist the drawing file, set saveDrawing=true; do not call Database.SaveAs or queue QSAVE from the C# code.
Inputs: code (required), expectedDrawing (required), description, saveDrawing, +1 more.
civil3d_queryA
Execute C# code in Civil 3D in READ-ONLY mode (no changes saved). Available globals: Document, CivilDoc, Database, Transaction, Editor. All Civil 3D namespaces are auto-imported. Return a value to get results as JSON. Use this for querying data: listing objects, getting properties, analyzing surfaces, etc. Omit expectedDrawing only to bootstrap Database.Filename and Database.FingerprintGuid; otherwise supply it to guard the active drawing.
Inputs: code (required), expectedDrawing.
civil3d_skillsA
Browse and read Civil 3D code skills (documented C# code templates). Use 'list' to see available skills, 'search' to find by keyword, 'get' to read the full skill with code template, or 'api_lookup' to search public metadata from already-loaded Civil 3D host assemblies. Skills are pre-built C# patterns you can adapt and execute via civil3d_execute or civil3d_query.
Inputs: action (required), limit, query, cursor, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clear, non-overlapping purpose: execute for write operations, query for read-only operations, and skills for browsing code templates. The read/write distinction is explicitly stated, so agents should not confuse execute and query.
All tools share the civil3d_ prefix and snake_case, but the suffixes mix verbs (execute, query) with a noun (skills), making it not a strictly consistent verb_noun pattern. The naming is still predictable and readable.
Three tools is a well-scoped set for a server that provides arbitrary C# execution capabilities; each tool serves a distinct and necessary function. The count falls within the typical 3-15 range.
The combination of execute and query covers the full range of Civil 3D operations (create, edit, delete, query), and skills fills the learning gap. No obvious missing functionality for the stated purpose.
Maintenance
Related MCP Connectors
AI for Revit: 450+ tools, 1 undo step. Windows, Revit 2024–2027 (2021–2023 included). Free account.
Read, query, edit and render DWG drawings with AI. No AutoCAD required.
Set up and run your firm's Precision AI agents, skills and routines from any MCP client.
One place to build, share, and govern the skills and tools your AI agents use at work.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Autodesk Civil 3D, allowing them to retrieve project data, create/modify/delete drawing elements, and execute code to automate Civil 3D operations.350MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to write and execute C# code directly inside Autodesk Civil 3D, providing full API access through code generation and execution.1102MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to interact with Autodesk Civil 3D through natural language, supporting tools for surfaces, alignments, profiles, corridors, pipe networks, COGO points, and AutoCAD geometry.94MIT
- AlicenseNot gradedqualityCmaintenanceLets any MCP-compatible AI assistant read and edit Autodesk Civil 3D drawings through tools for alignments, surfaces, corridors, pipe networks, quantity takeoff, and cut/fill, using a local bridge plugin and named pipes.MIT