OpenAEC MCP

OpenAEC MCP is an independent, safety-first Model Context Protocol platform for AEC applications. It separates MCP protocol handling from host-specific adapters so AI assistants can inspect, plan, validate, and—only after policy and approval checks—modify engineering documents.

Phase 1 is implemented: the server starts over stdio or authenticated Streamable HTTP, exposes tools/resources/prompts, negotiates capabilities, executes a complete plan → approve → transaction workflow against a synthetic in-memory adapter, emits redacted audit events, and passes protocol and safety tests. Desktop and cloud adapters remain explicitly unavailable until their public host APIs are implemented and verified.

Engineering disclaimer: AI-generated or automated engineering output is not a substitute for professional judgment. A qualified professional must review and approve work products, assumptions, units, coordinate systems, and applicable standards.

Architecture

flowchart LR
  Client["MCP client"] -->|"stdio or authenticated Streamable HTTP"| Server["MCP server core"]
  Server --> Catalog["Capability-gated tool catalog"]
  Catalog --> Safety["Safety and approval engine"]
  Safety --> Contract["Language-neutral adapter contract"]
  Contract --> Fake["In-memory CI adapter"]
  Contract -. "future verified adapters" .-> Hosts["AutoCAD · Civil 3D · Revit · QGIS · FreeCAD · APS"]
  Server --> Resources["Resources and prompts"]
  Safety --> Audit["Redacted audit log"]
  Contract --> Validation["Versioned validation rules"]

The detailed proposal, interaction model, risk register, milestones, final directory tree, and exact Phase 1 file manifest are in docs/architecture/phase-1.md.

Current support

Application / adapter	Status	Capability advertised
Synthetic in-memory adapter	Implemented and tested	Document reads, line plan/write, transactions, validation
AutoCAD	Planned Phase 2	None
Civil 3D	Planned Phase 3	None
QGIS	Planned Phase 4	None
Revit	Planned Phase 4	None
FreeCAD	Planned Phase 4	None
Autodesk Platform Services	Planned Phase 5	None

Unsupported applications are never simulated and their tools are not advertised. See compatibility strategy.

Quick start

Requirements: Node.js 22 or newer.

npm install
npm run build
node apps/mcp-server/dist/cli.js doctor
node apps/mcp-server/dist/cli.js

For a local MCP client after publication:

{
  "mcpServers": {
    "open-aec": {
      "command": "npx",
      "args": ["-y", "@venkatchavan/open-aec-mcp"]
    }
  }
}

During repository development, replace the command and arguments with node and the absolute path to apps/mcp-server/dist/cli.js.

Remote Streamable HTTP

HTTP binds to loopback by default and refuses to start without a bearer token of at least 32 characters.

OPENAEC_TRANSPORT=http \
OPENAEC_HTTP_TOKEN='replace-with-at-least-32-random-characters' \
node apps/mcp-server/dist/cli.js

Endpoints: POST /mcp, GET /health, and GET /ready. The MCP endpoint requires Authorization: Bearer …. Public binding is denied unless explicitly enabled; production remote deployment additionally requires a trusted TLS/authentication gateway.

Safety workflow

The default mode is inspect. It permits reads, calculations, and dry-run plans but blocks approval and execution.

1. Call aec.geometry.create_line_plan with explicit units, expected document ID/revision, transaction name, and idempotency key.
2. Review affected objects, warnings, CRS, files, approval requirements, and rollback strategy.
3. In assisted mode, call aec.transaction.approve_change_plan as an identified operator.
4. Call aec.transaction.execute_change_plan with the short-lived, plan-scoped approval token.
5. The engine rechecks policy, expiry, adapter, document revision, object limits, idempotency, and the per-document write lock before dispatch.

The test adapter uses snapshot rollback. Real adapters must use valid host-native transactions, document locks, and main-thread dispatch where required.

MCP surface

Phase 1 implements nine task-oriented tools under aec.system.*, aec.document.*, aec.geometry.*, aec.transaction.*, and aec.validation.*. Tool documentation is generated from source metadata with npm run docs:tools.

Resources include:

• aec://applications
• aec://documents
• aec://documents/{documentId}
• aec://documents/{documentId}/validation/latest
• aec://capabilities
• aec://standards
• aec://audit/history

All 14 requested engineering workflow prompts are registered. See resources and prompts.

CLI

open-aec-mcp
open-aec-mcp doctor
open-aec-mcp configure
open-aec-mcp list-adapters
open-aec-mcp validate-config ./open-aec.json

doctor checks Node, parsed configuration, installed adapters, bridge readiness, authentication, port conflicts for HTTP, and transport readiness without printing secrets.

Development and testing

npm run verify
npm run test:coverage

The test suite covers MCP discovery, policy enforcement, approval, stale revisions, idempotency, rollback, unit conversion, redaction, capability filtering, transport security, and validation reports. Use the official MCP Inspector as described in docs/testing.md.

Security

Drawing/model text, block attributes, metadata, external references, and linked-model content are untrusted data—not instructions. The server rejects public binding by default, hashes redacted inputs, never exposes a shell/eval tool, and never advertises unavailable host capabilities. Read SECURITY.md and the threat model before enabling writes.

Roadmap

• Phase 1: core, contracts, fake adapter, safety, audit, configuration, protocol surface, tests—implemented.
• Phase 2: verified AutoCAD public API adapter and packaging.
• Phase 3: verified Civil 3D vertical workflows.
• Phase 4: QGIS, Revit, and FreeCAD adapters.
• Phase 5: APS adapter and hardened remote deployment.
• Phase 6: installers, conformance/performance hardening, signed release artifacts, and registry publishing.

Limitations

• Only the synthetic adapter is enabled in Phase 1.
• Change plans and approvals are in memory; process restart invalidates them.
• HTTP is stateless at the MCP transport layer; application state is shared in the server runtime.
• Validation rules are examples and advisory, not jurisdiction-specific design standards.
• Binary desktop plugins, installers, signing, APS, and production database persistence are later-phase work.

Trademark and affiliation disclaimer

OpenAEC MCP is independent community software. It is not affiliated with, endorsed by, sponsored by, or an official product of Autodesk, QGIS.org, the FreeCAD project, or any other vendor. Autodesk, AutoCAD, Civil 3D, Revit, QGIS, FreeCAD, and other product names are trademarks of their respective owners and are used only for truthful compatibility descriptions. No third-party logos are included.

Licensed under Apache-2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.