Agents and MCP
How external agents inspect, reason over, and update Scopture project state under the same access and version controls as the application.
Automation in Project Context
Scopture exposes a Model Context Protocol (MCP) server so compatible agents can work with drawings, models, charter records, issues, external files, and version history. Automation operates on the same project context that people review in the application; it is not a separate copy of the drawing.
The integration is intended for bounded engineering and review tasks: inspecting the active drawing, locating relevant elements, calculating or generating an addition, recording an issue or decision, and verifying the result in context.
Connect an Agent
The MCP endpoint and connection controls are available from Settings → Integrations. Use the client’s OAuth flow when it supports remote MCP authentication. API keys are available for clients that cannot complete OAuth; they are scoped, revocable, displayed only when created, and should be stored as credentials.
Integration permissions separate three capabilities:
| Scope | Capability |
|---|---|
| Read | Inspect accessible drawings and their project context |
| Write | Change drawing records, charter data, issues, and related state |
| Execute | Run supported Python or SQL jobs against an accessible drawing |
These scopes do not bypass drawing or organization permissions. The connected identity must also have the access required for the requested operation.
What an Agent Can Do
Scopture’s MCP tools cover five functional areas:
- Orient — identify the active drawing, current application context, visible state, and available drawings.
- Inspect — search elements, read drawing records, retrieve external files, inspect versions, and capture screenshots.
- Trace — read and maintain the charter, requirements, constraints, decisions, issues, and issue messages.
- Change — create or update drawing content and switch application modes when an operation requires focused model interaction.
- Compute and recover — run Python or SQLite work, export assets, inspect job results, and restore a known version or automated change boundary.
Tool descriptions and input schemas are the authoritative reference for individual operations. They remain closer to the running service than a static copy of every argument in this documentation.
Execution Model
An effective agent workflow is:
- Resolve the drawing and inspect its current context.
- Retrieve only the records and external assets needed for the task.
- Perform a narrow calculation, query, or edit.
- Poll asynchronous Python or SQL work instead of submitting the same job again.
- Verify the result through the updated records, a drawing screenshot, or Model Open mode.
- Leave the automatic version delta as the recoverable boundary for the operation.
Remote automation requires a remote drawing. Local drawings remain device-resident and are not available to the server unless they are moved to the cloud or accessed through a supported application bridge.
Python and SQLite
The Python environment is an isolated Python 3.12 sandbox with Duc-aware drawing helpers and engineering libraries including NumPy, SciPy, SymPy, Pint, pandas, Matplotlib, and Fluids. It can read the current .duc data, resolve referenced files, perform engineering calculations, and submit drawing changes.
Drawing updates use patch semantics. The update should contain only records that were added or changed:
- an existing ID updates the corresponding record;
- a new ID adds a record;
- omitted records remain unchanged; and
- an element is deleted by updating its
is_deletedfield totrue.
It is therefore unnecessary—and undesirable—to fetch, rewrite, and submit the complete drawing for a localized change.
SQLite jobs provide direct structured access to the .duc database through the supported Duc query layer. Use them for targeted inspection or mutation when the task is naturally relational. Use Python when the task requires calculations, geometry generation, external-file processing, or multi-step drawing logic.
Prefer the narrowest valid mutation
Read the current state before writing, preserve existing IDs and relationships, and submit only the intended patch. Automated changes are versioned, but a recoverable history is not a substitute for a well-scoped operation.
Verification and Recovery
A successful tool response proves that an operation completed, not that the resulting drawing communicates the intended outcome. Agents should inspect the changed records and use a screenshot or interactive model view when visual placement or geometry matters.
Scopture records agent operations as automatic deltas in the drawing’s version graph. Those boundaries can be inspected and restored without treating automation as an opaque side channel.
For the underlying .duc storage and element model, see the Duc documentation.
Last updated on