MCP Tool Reference

AI-ERD's MCP server defines 60 tools. The names below are what the server publishes — what you send in a tools/call.

Your MCP client adds its own prefix on top, built from the server name you registered. Register it as ai-erd and list_documents shows up in your assistant as mcp__ai-erd__list_documents. Only the client-side prefix changes; the names on this page do not.

The catalog is split into four groups:

Group	Count	Scope
Generic backbone	38	Workspaces, projects, folders, documents, versions, sharing, attachments, search, identity
ERD	10	ERD content: read tables, refs, table groups, enums; one batch apply; auto layout
Diagram	10	Diagram nodes, edges, groups; one batch apply; LLM request handoff
Markdown	2	Markdown append and AI generation helpers

Groups are opened gradually, so your server's tools/list may not show every group yet. tools/list is the machine-readable source for the exact tools and JSON Schemas available to you; this page summarizes the same catalog in a prompt-friendly form.

Naming Rules

Tool names are plain snake_case — no server-side prefix.
Document types are erd, diagram, markdown, and openapi. Which types you can create through MCP is listed in the type enum of create_documents.
Top-level groups are called workspaces. Use workspaceUuid / workspaceId; do not use groupUuid for workspaces.
Documents of every type are created, listed, updated, and deleted with the generic document tools: create_documents, list_documents, get_document, update_documents, delete_documents.
ERD content tools use documentUuid for the parent ERD document.
Diagram content tools use diagramUuid for the parent diagram document.
Public sharing is unified: enable_shares(targetType=project|folder|document, targetUuids) and disable_shares(...).

Generic Backbone Tools (38)

Tool	Main input shape	Purpose
`list_workspaces`	none	List workspaces visible to the user
`get_workspace`	`uuid`	Get one workspace
`create_workspaces`	`items[]`	Create workspaces
`update_workspaces`	`items[].uuid`	Rename/update workspaces
`delete_workspaces`	`uuids[]`	Archive workspaces
`unarchive_workspaces`	`uuids[]`	Restore archived workspaces
`list_projects`	`workspaceUuid?`	List projects
`get_project`	`uuid`	Get one project
`create_projects`	`items[].workspaceUuid`, `items[].name`	Create projects
`update_projects`	`items[].uuid`	Update projects
`delete_projects`	`uuids[]`	Archive projects
`unarchive_projects`	`uuids[]`	Restore archived projects
`list_folders`	`projectUuid?`, `parentUuid?`	List folders
`create_folders`	`items[].projectUuid`, `items[].name`	Create folders
`update_folders`	`items[].uuid`	Rename folders
`move_folders`	`items[].uuid`, `items[].parentUuid?`	Move folders
`delete_folders`	`uuids[]`	Archive folders
`unarchive_folders`	`uuids[]`	Restore archived folders
`list_documents`	`projectUuid?`, `folderUuid?`, `type?`, `q?`, `limit?`	List or search documents
`get_document`	`uuid`	Get one document
`create_documents`	`items[].projectUuid`, `items[].type`, `items[].title`, `items[].typePayload?`	Create ERD, diagram, Markdown, or OpenAPI documents
`update_documents`	`items[].uuid`, `items[].title?`, `items[].typePayload?`	Update document metadata or type-specific payload
`move_documents`	`items[].uuid`, `items[].folderUuid?`	Move documents
`delete_documents`	`uuids[]`	Archive documents
`unarchive_documents`	`uuids[]`	Restore archived documents
`list_trash`	optional filters	List archived resources
`list_versions`	`documentUuid`	List document versions
`get_version`	`documentUuid`, `version`	Get a version snapshot
`restore_versions`	`items[].documentUuid`, `items[].version`	Restore previous versions
`enable_shares`	`targetType`, `targetUuids[]`	Enable public sharing for projects, folders, or documents
`disable_shares`	`targetType`, `targetUuids[]`	Disable public sharing
`list_attachments`	`projectUuid?`, `documentUuid?`	List attachments
`get_attachment`	`uuid`	Get attachment metadata
`upload_attachments`	`items[]`	Upload attachment files
`delete_attachments`	`uuids[]`	Delete/archive attachments
`request_upload_token`	`purpose`, `scopeJson?`, `maxBytes?`, `ttlSeconds?`	Issue an upload or one-shot MCP call token
`search_documents`	`q`, `type?`, `projectUuid?`, `limit?`, `offset?`	Full-text search over documents
`identity_get_self`	none	Return the signed-in user

Document CUD Schema

Use the plural document CUD tools. Each items[] element carries a document type and an optional typePayload.

{
  "items": [
    {
      "projectUuid": "<project-uuid>",
      "folderUuid": "<optional-folder-uuid>",
      "type": "erd",
      "title": "Production schema",
      "typePayload": {}
    }
  ]
}

Type-specific payloads:

Type	`typePayload`
`erd`	Usually empty on create; ERD content is managed with `erd_*` tools
`diagram`	`diagramSource?`, `sourceLanguage?`, `edgeStyle?`, `isModule?`, `metadata?`
`markdown`	`body`
`openapi`	`content` — the OpenAPI / Swagger source (YAML or JSON), stored as written

For large bodies, issue request_upload_token with purpose=document.create, document.update, or document.append and upload the body directly instead of passing it through a chat prompt.

ERD Tools (10)

ERD document lifecycle is generic. Use list_documents(type=erd) to find an ERD document, then pass its UUID as documentUuid to these tools.

Tool	Main input shape	Purpose
`erd_apply_changes`	`documentUuid`, `description`, `operations[]`, `arrangeNewTables?`	The only create/update/delete path for ERD content
`erd_arrange_tables`	`documentUuid`, `full?`	Auto-arrange new tables, or the whole ERD with `full=true`
`erd_list_tables`	`documentUuid`	List tables
`erd_get_table`	`documentUuid`, `tableUuid`	Get one table with its columns and indexes
`erd_list_refs`	`documentUuid`	List relationships
`erd_get_ref`	`documentUuid`, `refUuid`	Get one relationship
`erd_list_table_groups`	`documentUuid`	List table groups
`erd_get_table_group`	`documentUuid`, `tableGroupUuid`	Get one table group
`erd_list_enums`	`documentUuid`	List enums
`erd_get_enum`	`documentUuid`, `enumUuid`	Get one enum

erd_apply_changes.operations[] items are {op: create|update|delete, type, uuid?, data?}:

type is one of table, column, index, index_column, ref, ref_column, enum, enum_value, table_group, table_group_table, table_group_note, filter, note.
data field names are snake_case (table_uuid, is_pk, from_table_uuid, …).
On create, you may supply your own data.uuid; later operations in the same batch can reference it. uuid on the operation itself is only the update/delete target.
ref.relationship is >, <, or -. Foreign-key columns are mapped with explicit ref_column operations. Enum values are separate enum_value operations.

Diagram Tools (10)

Diagram document lifecycle is generic. Use create_documents(type=diagram) or list_documents(type=diagram) for the document itself, then pass its UUID as diagramUuid.

Tool	Main input shape	Purpose
`diagram_apply_changes`	`diagramUuid`, `description`, `nodes?`, `edges?`, `groups?`	The only create/update/delete path for nodes, edges, and groups
`diagram_list_nodes`	`diagramUuid`	List nodes
`diagram_get_node`	`nodeUuid`	Get one node
`diagram_list_edges`	`diagramUuid`	List edges
`diagram_get_edge`	`edgeUuid`	Get one edge
`diagram_list_groups`	`diagramUuid`	List groups
`diagram_get_group`	`groupUuid`	Get one group
`diagram_get_pending_llm_requests`	none	List pending LLM handoff requests
`diagram_submit_llm_result`	`uuid`, `result`, token counts	Submit an LLM handoff result
`diagram_update_llm_request_status`	`uuid`, `status=FAILED`, `errorMessage?`	Mark an LLM handoff request as failed

diagram_apply_changes uses action: create|update|delete on each node, edge, or group item. Node fields include text, shape, x, y, width, height, groupUuid, fillColor, strokeColor, and textColor. Edge fields include fromUuid, toUuid, label, lineStyle, strokeColor, and strokeWidth. Group fields include name, color, parentGroupUuid, width, and height.

Markdown Tools (2)

Markdown document create/update is generic. Use typePayload.body with create_documents(type=markdown) or update_documents for full-body writes.

Tool	Main input shape	Purpose
`markdown_append_document`	document append payload	Append markdown to an existing Markdown document
`markdown_generate_document`	prompt/project payload	Generate a Markdown document with AI

CLI command paths mirror the same public surface: documents create, documents update, markdown append-document, and markdown generate-document.

Examples

Discover ERD documents

{
  "name": "list_documents",
  "arguments": {
    "type": "erd",
    "q": "production schema",
    "limit": 10
  }
}

Create an ERD document

{
  "name": "create_documents",
  "arguments": {
    "items": [
      {
        "projectUuid": "<project-uuid>",
        "type": "erd",
        "title": "Billing schema"
      }
    ]
  }
}

Create tables and a foreign key in one call

{
  "name": "erd_apply_changes",
  "arguments": {
    "documentUuid": "<erd-document-uuid>",
    "description": "Add notifications with a FK to users",
    "operations": [
      {"op": "create", "type": "table", "data": {"uuid": "tbl_notifications", "name": "notifications"}},
      {"op": "create", "type": "column", "data": {"uuid": "col_n_id", "table_uuid": "tbl_notifications", "name": "id", "type": "bigint", "is_pk": true, "is_not_null": true}},
      {"op": "create", "type": "column", "data": {"uuid": "col_n_user_id", "table_uuid": "tbl_notifications", "name": "user_id", "type": "bigint", "is_not_null": true}},
      {"op": "create", "type": "ref", "data": {"uuid": "ref_n_user", "from_table_uuid": "tbl_notifications", "to_table_uuid": "<users-table-uuid>", "relationship": ">", "on_delete": "CASCADE"}},
      {"op": "create", "type": "ref_column", "data": {"ref_uuid": "ref_n_user", "from_column_uuid": "col_n_user_id", "to_column_uuid": "<users-id-column-uuid>"}}
    ]
  }
}

Get existing table and column UUIDs with erd_get_table.

Create a Markdown document

{
  "name": "create_documents",
  "arguments": {
    "items": [
      {
        "projectUuid": "<project-uuid>",
        "type": "markdown",
        "title": "API notes",
        "typePayload": {
          "body": "# API notes\n\nInitial draft."
        }
      }
    ]
  }
}

{
  "name": "enable_shares",
  "arguments": {
    "targetType": "document",
    "targetUuids": ["<document-uuid>"]
  }
}

Error Handling

Tools return standard JSON-RPC error responses. Common cases:

Error	Cause
`401 Unauthorized`	Token missing or expired; re-authenticate
`403 Forbidden`	Your account lacks view or edit access
`404 Not Found`	Workspace, project, folder, document, or entity UUID is wrong
`409 Conflict`	Concurrent edit conflict; read current state and retry
`429 Too Many Requests`	Rate limit hit; back off and retry

Naming Rules​

Generic Backbone Tools (38)​

Document CUD Schema​

ERD Tools (10)​

Diagram Tools (10)​

Markdown Tools (2)​

Examples​

Discover ERD documents​

Create an ERD document​

Create tables and a foreign key in one call​

Create a Markdown document​

Share a document​

Error Handling​