Connect your AI agent to Modudraft
Modudraft exposes a Model Context Protocol (MCP) server that lets Claude, Cursor, or any MCP-compatible client read and modify your cloud diagrams. Your agent can build architecture diagrams, generate sequence flows, scaffold DB schemas, define API endpoints, write notes, manage which tabs are visible, and fill in node metadata — all from a chat window.
The MCP integration requires a Modudraft Pro account and an API key. Changes made by your agent appear instantly in your open diagram.
Authentication
The MCP server authenticates using an API key you create in your dashboard. Keys are scoped to diagram read/write — they cannot access account settings or create new keys.
Create an API key
- Go to app.modudraft.com/dashboard
- Click Settings in the left sidebar
- Under API Keys, enter a name (e.g. "Claude Desktop") and choose an expiry
- Click Create — copy the key immediately, it won't be shown again
Keys start with mdft_ and expire after the period you choose (30 days, 90 days, 1 year, or never). You can revoke a key at any time from the Settings page.
Installation
No install needed. The server runs on demand via npx:
MODUDRAFT_API_KEY=mdft_your_key npx -y @modudraft/mcpOr install globally for faster startup:
npm install -g @modudraft/mcpConnecting a client
Claude Desktop
Add the following to your Claude Desktop configuration
(~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"modudraft": {
"command": "npx",
"args": ["-y", "@modudraft/mcp"],
"env": {
"MODUDRAFT_API_KEY": "mdft_your_key_here"
}
}
}
}Restart Claude Desktop. You should see the Modudraft tools in the tools panel.
Cursor
Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):
{
"mcpServers": {
"modudraft": {
"command": "npx",
"args": ["-y", "@modudraft/mcp"],
"env": {
"MODUDRAFT_API_KEY": "mdft_your_key_here"
}
}
}
}Any MCP client
Point your client at npx -y @modudraft/mcp with the
MODUDRAFT_API_KEY environment variable set.
The server uses stdio transport — compatible with all standard MCP clients.
Diagram management
Every tool requires a diagram_id. Use list_diagrams to find yours or create_diagram to start fresh.
list_diagrams List all diagrams in your account create_diagram Create a new diagram (uses your personal workspace) get_diagram Get full diagram state — nodes, edges, sequence, DB schema, API schema, and metadata hints delete_diagram Move diagram to Bin (recoverable for 30 days) clear_diagram Remove all content from a diagram layout_diagram Auto-arrange nodes with dagre (direction: LR, TB, RL, BT) get_share_link Get or create a share link for the diagram Nodes & edges
add_node Add a component with archetype (compute, database, queue…), optional tool (postgresql, redis…), and position update_node Change a node's label, tool, or archetype delete_node Remove a node and all its connected edges add_edge Connect two nodes with an optional label and protocol update_edge Change an edge's label or protocol delete_edge Remove a connection add_boundary Add a grouping boundary box around a set of nodes add_note Add a sticky-note annotation to the canvas Node metadata
Each archetype has well-known configuration fields — for example, a database node
expects host, port, replication, and engine-version.
Use these tools to fill in and discover missing configuration.
set_node_metadata Set a single property on a node (e.g. host, port, framework, region) suggest_metadata Scan the diagram and return nodes with missing configuration fields — ask the user to fill them in get_node_schema Get the expected metadata fields for an archetype so you know what to ask for get_diagram returns a hints[] array listing every node with empty metadata fields.
A good workflow: build the architecture first, then call suggest_metadata and ask
the user for hostnames, regions, frameworks, and other config details before saving.
Sequence diagram
add_sequence_message Add a message between two participants (sync, async, return, create, destroy, note) add_sequence_participant Register a named participant explicitly auto_sequence Derive a sequence diagram from the architecture edges — one message per edge generate_sequence_from_api Generate a richer sequence diagram from the API tab — groups endpoints by tag or URL prefix, creates one participant per group, and adds request + response message pairs in HTTP method order. Much more detailed than auto_sequence clear_sequence Remove all sequence messages (leaves architecture untouched) Sequence fragments
Fragments annotate a group of messages with a flow control label — loop,
alt (conditional), opt (optional), or par (parallel).
Each fragment references the message IDs it wraps.
add_sequence_fragment Wrap a set of messages in a fragment — supply kind (loop / alt / opt / par), a condition label (e.g. "payment fails"), and the message_ids to include update_sequence_fragment Change a fragment's kind, condition, or message_ids delete_sequence_fragment Remove a fragment by fragment_id (messages are kept) DB schema (ER diagram)
add_db_table Add a table with columns to a database node's schema update_db_table Replace a table's column list delete_db_table Remove a table from the schema export_er_diagram Export the DB schema as SQL DDL (CREATE TABLE statements) API schema (OpenAPI)
add_api_endpoint Add a REST, GraphQL, gRPC, WebSocket, or event-based endpoint to a service node update_api_endpoint Update path, method, summary, or tags delete_api_endpoint Remove an endpoint export_openapi Export the API schema as an OpenAPI 3.0 JSON document Notes
Each diagram has a global Markdown notes field — useful for ADRs, runbooks, meeting notes, and sprint plans. Notes are visible in the Notes tab in the editor and persist as part of the diagram file.
get_notes Return the current notes content for a diagram set_notes Replace the notes with new Markdown content append_to_notes Append content to the end of the existing notes — useful for adding meeting notes or decisions without overwriting what's already there Tab management
Each diagram can show a custom subset of the 8 available tabs: Architecture, Sequence, DB Schema, API Schema, Cloud, Data Flow, Network, and Notes. By default all tabs are visible. Use these tools to tailor the view to the role or use case.
get_enabled_tabs Return the list of tabs currently visible in the diagram. When all tabs are visible (the default), returns all 8 tab types enable_tab Make a tab visible — adds it to the enabled set. If the diagram already shows all tabs, this is a no-op disable_tab Hide a tab without deleting its data. When disabling from an all-tabs state, the remaining 7 tabs become the explicit set. The tab can be re-enabled at any time Discovery (static)
These tools return static catalog data — no diagram needed.
list_archetypes All 23 node archetypes with their expected metadata fields and default tools list_tools Available technology tools per archetype (postgresql, redis, kafka, aws-ec2…) list_protocols Valid edge protocol values (HTTPS, gRPC, Kafka, WebSocket, GraphQL…) Cloud resources
Manage the Cloud diagram tab — K8s clusters, VPCs, subnets, and cloud provider resources. Resources can be nested (e.g. a pod inside a namespace inside a cluster).
add_cloud_resource Add a resource (k8s-cluster, vpc, subnet, ec2, rds, s3, lambda…) — supply type, name, optional parent_id for nesting, and optional key-value config delete_cloud_resource Remove a cloud resource and all its children by resource_id update_cloud_resource Change a resource's name, type, or config Network devices
Manage the Network diagram tab — routers, switches, firewalls, racks, and zones. Devices can be nested (e.g. a server inside a rack inside a zone).
add_network_device Add a device (router, switch, firewall, server, access-point, load-balancer, rack, zone…) — supply type, name, optional parent_id for grouping, and optional key-value config delete_network_device Remove a network device and all its children by device_id update_network_device Change a device's name, type, or config Data flow
Manage the Data Flow diagram tab. You can group stages into named flows, or leave them ungrouped. Stages have a role of source, transform, or sink, an optional technology tool (kafka, spark, dbt, s3…), and an optional description to explain what each stage does. Flows also support edge notes on the arrows between columns.
add_data_flow Create a named flow (e.g. "Ingestion pipeline") — returns a flow_id you can attach stages to. Optional: source_to_transform_note and transform_to_sink_note set labels on the connecting arrows list_data_flows List all named flows in the diagram add_data_flow_stage Add a stage — supply type (source / transform / sink), a label, an optional tool slug (e.g. "kafka", "spark", "dbt", "s3"), an optional flow_id to scope it to a named flow, and an optional description to explain what the stage does delete_data_flow_stage Remove a stage by stage_id update_data_flow_stage Change a stage's type, tool, label, and/or description reorder_data_flow_stages Reorder all stages by providing the complete ordered array of stage_ids File import
Import existing files from your project directly into a diagram. Use scan_project to
discover what's importable, then import_file to bring it in. Format is detected
automatically from the file path and content.
scan_project Recursively scan a directory and return all importable files with their detected formats — run this first to discover what you can import read_file Read any file from the filesystem and return its raw content — useful for files you want to inspect before importing import_file Import a file into the diagram — auto-detects format; supply an optional target_tab to override Supported import formats
docker-compose.yml Architecture — one node per service, edges from depends_on Kubernetes YAML Cloud tab — Deployment, Service, Ingress, StatefulSet, ConfigMap, Secret, and more Terraform .tf Cloud tab — aws_*, google_*, azurerm_* resources with dependency edges AWS CloudFormation YAML/JSON Cloud tab — 60+ AWS::* resource type mappings with DependsOn edges SQL DDL (.sql) DB schema tab — CREATE TABLE with columns, PKs, FKs, indexes, defaults schema.prisma DB schema tab — model blocks with @relation FK resolution DBML (.dbml) DB schema tab — dbdiagram.io format, inline [ref: >] and standalone Ref: declarations schema.rb (Rails) DB schema tab — create_table blocks, t.timestamps, add_foreign_key TypeORM entities DB schema tab — @Entity, @Column, @ManyToOne, @OneToOne decorators SQLAlchemy models DB schema tab — Column() definitions with ForeignKey() resolution across models dbt schema.yml DB schema tab — models and sources with column tests: (unique, not_null, relationships) OpenAPI 2.x / 3.x API tab — paths, methods, tags, request body, and response codes GraphQL SDL (.graphql) API tab — Query, Mutation, and Subscription fields as endpoints Protocol Buffers (.proto) API tab — service + rpc blocks; detects UNARY, SERVER_STREAM, CLIENT_STREAM Postman collection v2.1 API tab — all requests from nested folders, folder names become tags Insomnia export v4 API tab — requests from all resource groups AsyncAPI YAML/JSON API tab — channels as PUBLISH / SUBSCRIBE endpoints (v2.x and v3.x) .env / .env.example Context only — returns filtered topology metadata (host, port, database, region); sensitive values are always redacted package.json, go.mod, requirements.txt, Gemfile, pom.xml, Cargo.toml Context only — returns a tech-stack summary so the agent can make better architecture suggestions .env security: only topology metadata is ever extracted — hostnames, ports, database names,
and regions. Passwords, tokens, API keys, and any high-entropy string are always replaced with
[REDACTED] regardless of key name.
Export
Export a diagram to a standard format. All export tools return the generated content as a string.
Use export_to_file to write the output directly to a path on disk.
export_mermaid Export architecture as a Mermaid flowchart, or DB schema as an ER diagram — paste directly into GitHub Markdown export_plantuml Export architecture as a PlantUML component diagram export_drawio Export architecture or DB schema as draw.io / diagrams.net XML — open in diagrams.net or VS Code export_terraform Generate Terraform resource stubs from the cloud tab — provider blocks pre-filled, known config attrs included export_k8s_yaml Generate Kubernetes YAML manifests from cloud resources with type k8s-* — Deployment, Service, Ingress, ConfigMap, Secret stubs export_er_diagram Export the DB schema tab as SQL DDL (CREATE TABLE statements) export_openapi Export the API tab as an OpenAPI 3.0 JSON document export_to_file Write any export format to a local file path — supports mermaid, plantuml, drawio, terraform, k8s, sql, openapi Validation & diff
validate_diagram Check a diagram for issues — dangling edges, orphaned nodes, tables with no PK, duplicate column names, FK references to non-existent tables, duplicate API routes, cloud resources with invalid parent IDs. Returns structured issues with severity (error / warning / info) diff_diagram Compare two diagrams and return a list of changes — nodes, edges, tables, endpoints, and cloud resources that were added, removed, or modified. Useful as a CI check after a PR Cross-diagram intelligence
find_shared_services Scan multiple diagrams and find nodes that appear in more than one — identified by matching label and archetype. Useful for auditing shared infrastructure suggest_connections Detect likely missing edges based on archetype pairs — e.g. a service node and a database node with no edge between them probably need one suggest_architecture Generate a suggested node and edge structure from a text description. Pass an optional diagram_id to enable extend mode — the tool fetches what's already in the diagram and only suggests components that are missing, so it adds to your work rather than replacing it clone_diagram Deep-copy a diagram under a new name — all IDs are remapped, useful for creating variant architectures from a template Org context
The server maintains a local cache of your organization's existing tools, protocols, and naming
conventions — derived from scanning your diagrams. This context is used by suggest_architecture
and suggest_metadata to make suggestions that match how your team already builds.
get_org_context Return the cached org context — most-used tools, protocols, archetypes, and naming patterns across all your diagrams refresh_org_context Force a fresh scan of your diagrams to rebuild the org context cache (cached for 7 days by default) Bulk operations
Add many nodes and edges in a single tool call. The key tool is
apply_architecture — it takes the output of suggest_architecture
directly (nodes array + edges with from_label/to_label) and applies
everything in one shot, including auto-layout.
apply_architecture 1-shot: add all nodes and edges from a suggest_architecture response in a single call. Edges are matched by label — no need to track IDs. Runs auto-layout afterward bulk_add_nodes Add multiple nodes at once — returns a label → id map for use with bulk_add_edges bulk_add_edges Add multiple edges at once — reference nodes by ID (source_id/target_id) or by label (source_label/target_label) Snapshots
Save named checkpoints before risky edits. restore_snapshot automatically saves
the current state as a "before restore" snapshot before overwriting, so you can always undo the undo.
Up to 10 snapshots per diagram, stored in ~/.modudraft/snapshots.json.
snapshot_diagram Save the current diagram state with a label (e.g. "before refactor", "v1 baseline") list_snapshots List all saved snapshots for a diagram, newest first restore_snapshot Restore a diagram to a saved snapshot — auto-saves current state first so you can always undo delete_snapshot Delete a snapshot by ID Edit history
Every mutation tool (add, update, delete, import, layout, etc.) is automatically logged after a
successful call. The log persists in ~/.modudraft/edit-log.json across sessions,
keyed by diagram ID.
get_edit_log Return the recent edit history for a diagram — tool name, human-readable summary, and timestamp for each call. Returns up to 50 entries, newest first. Useful for answering "what did we change?" without re-fetching the full diagram Project watch
Associate a local project directory with a diagram. After the initial snapshot, the MCP server
can detect which files changed so you know exactly what needs to be re-imported.
get_diagram will also proactively hint when watched files have changed.
watch_project Scan a directory and save a snapshot of all importable files (path, format, size, modified time). Stored in ~/.modudraft/watch.json check_project_drift Re-scan the watched directory and compare against the snapshot — returns lists of added, modified, and removed files so you know exactly what to re-import unwatch_project Remove the watch association for a diagram
After calling watch_project, every get_diagram response will include
a hint if any watched files have changed — even if you haven't explicitly run
check_project_drift. This makes your diagrams a living document that stays in
sync with your codebase.
Search
Search across all your diagrams by node label, archetype, or technology — without fetching every diagram manually.
search_diagrams Search node labels, archetypes, and tool names across all diagrams. Returns matching diagrams and the specific nodes that matched. Scope to label, archetype, or tool, or search all three at once Env auto-apply
Parse a .env or .env.example file and automatically fill in node
metadata — no manual matching needed. Sensitive values are always redacted; only topology
metadata (host, port, database name, region) is applied.
apply_env_to_nodes Match env vars to nodes by label prefix (e.g. POSTGRES_HOST → node labelled "Postgres") and auto-fill metadata. Reports ambiguous matches that need manual assignment Docs & runbook
Generate structured Markdown documents directly from a diagram — no manual writing required.
Both tools optionally write to a file path via output_path.
import_directory Scan a directory and import all importable files in one call, in the right order: architecture first, then cloud, then DB schemas, then API specs generate_docs Generate an architecture document — Mermaid diagram, component table, connection summary, DB schema, API endpoints, sequence diagram. Paste into README, PR, or wiki generate_runbook Generate an incident response runbook — services table with host/port/restart commands, per-service dependency map, blast-radius analysis (what breaks when X goes down), health check URLs, happy-path sequence diagram, and incident checklist Examples
Design a microservices architecture
Create a new Modudraft diagram called "E-commerce backend". Add an API
gateway, user service, product service, order service, and Postgres databases
for each service. Connect them and run a left-to-right layout.Fill in node configuration from your environment
Check my Modudraft diagram for missing metadata. I'll share my .env file
— use the hostnames and ports to fill in the database and cache nodes.Generate a sequence diagram from the architecture
Look at my Modudraft architecture diagram and auto-generate a sequence
diagram showing the user checkout flow.Scaffold a DB schema
Add the DB schema for the order service node: orders, order_items,
and payments tables with the right columns and foreign keys. Then export
the SQL DDL.Add a retry loop to a sequence diagram
In my Modudraft sequence diagram, wrap the payment-service messages
in a loop fragment with condition "retry up to 3 times on timeout".Map a cloud deployment
Add a Cloud diagram showing a VPC with two private subnets,
an RDS instance, an ECS cluster, and an Application Load Balancer.Export the API contract
Add REST endpoints to the API gateway in my Modudraft diagram —
GET /users, POST /orders, GET /products. Export the OpenAPI spec.Scan a project and import everything
Scan ~/code/myapp and import everything you find into diagram "My App".
Start with the docker-compose, then Prisma schema, then OpenAPI spec.Import a Terraform stack into a cloud diagram
Import infra/main.tf into the cloud tab of diagram "Production Infra".
Then layout the diagram top-to-bottom.Validate a diagram before a deploy
Validate diagram "Checkout Service". Tell me about any dangling edges,
orphaned nodes, or DB tables with missing primary keys.Diff two versions of a diagram
Compare diagram "v1 Architecture" with "v2 Architecture" — what nodes,
edges, and tables changed between the two versions?Suggest an architecture from a text description
Suggest an architecture for a checkout service that uses Stripe for
payments, Postgres for orders, Redis for session caching, and publishes
events to Kafka. Add the suggested nodes and edges to diagram "Checkout".Export a diagram to a local file
Export diagram "Production Infra" as Terraform stubs and save the file
to ./infra/generated.tf. Then export the architecture as Mermaid and
append it to ./docs/architecture.md.Find shared infrastructure across diagrams
Which services appear in more than one of our diagrams?
I want to know what's shared so we can extract it into a shared-services diagram.Generate a rich sequence diagram from an imported API spec
Import our openapi.yaml into diagram "Checkout Service", then generate a
sequence diagram from the API endpoints — group by tag, include response messages.Keep a diagram in sync with the codebase
Watch ~/code/myapp for diagram "My App". Then, every time I ask you to
check the diagram, tell me if any files have drifted and offer to re-import them.Recap what changed in this session
What did we add to diagram "Checkout Service" in this session?
Show me the edit history.Extend an existing diagram from a description
We're adding a fraud-detection service that uses a Kafka topic and
a Redis cache. Suggest what to add to diagram "Checkout Service" — only
the pieces that aren't already there.Build a full architecture in one shot
Suggest an architecture for a SaaS platform with a React frontend,
API gateway, auth service, Postgres, Redis, and Kafka — then apply it
to diagram "Platform v2" in one call and layout the result.Snapshot before a big refactor
Save a snapshot of diagram "Checkout Service" labelled "before
microservices split", then split the monolith into three services.
If anything looks wrong, restore the snapshot.Find where a technology is used across diagrams
Search all our diagrams for "kafka" — show me every diagram that
uses Kafka and which nodes reference it.Auto-fill node metadata from the environment
Apply our .env.production file to diagram "Production" — fill in
host, port, and database name for every node you can match automatically,
and tell me which ones need manual input.Generate a runbook for on-call
Generate an incident runbook from diagram "Checkout Service" and
save it to ./docs/runbook.md — I want the blast radius table and
restart commands for each service.Import an entire project in one call
Import everything from ~/code/myapp into diagram "My App" in one go —
docker-compose, Prisma schema, and OpenAPI spec.Write an ADR into the Notes tab
Write an ADR for the decision to use Kafka over RabbitMQ in diagram
"Event Platform" and save it to the Notes tab.Append meeting notes to an existing diagram
Append today's architecture review notes to diagram "Checkout Service" —
we decided to add a Redis cache in front of the product service and to
deprecate the synchronous inventory check.Tailor a diagram to a specific role
For diagram "Product Overview", hide the Cloud and Network tabs —
this is for the backend team who only care about Architecture, Sequence,
DB Schema, and API.