Try DrawSQL

Reference

MCP tools

.md

Advanced reference for the DrawSQL MCP server. Look up tool inputs, outputs, errors, limits, and annotations. For client setup and a first diagram, start with the getting started guide.

How tools respond

The server is at https://drawsql.app/mcp over streamable HTTP. Every tool returns one text block, written in Markdown for the model to read. An error is a tool result too: isError is true and the text says what went wrong and how to fix it. Some error messages begin with their code, such as invalid_request:; the tables below show which.

Tools that create something reply with counts, never with your table or column names, so a reply cannot carry instructions hidden in a schema. get_schema is the exception: returning the schema is its job.

Authentication

visualize_schema needs no account. Every other tool needs a DrawSQL API token, sent on the MCP connection as an Authorization: Bearer <token> header. Create one under Account → API tokens. Tokens are available on paid plans, and each token belongs to one team.

The tool list depends on the header:

Connection Tools it adds to the list
No Authorization header visualize_schema
Any bearer token list_diagrams, get_schema, get_diagram_link
Any bearer token, for the write loop get_driver_rules, get_proposal_status
A token with Read and write access create_diagram, propose_diagram_changes

Each row adds to the rows above it.

The list checks only that a header is present; write tools also need a token with write access. The token itself is checked on every call. Calling a tool that is not in your list returns a JSON-RPC error, code -32602, message Tool [name] not found.

These errors can come from any tool that needs a token:

Code When The agent reads
invalid_token The token is unknown, expired, or revoked. "This API token is invalid, expired, or revoked. Create a new one under Account → API tokens."
invalid_token The token's team is gone, or its user left the team. "This API token no longer grants access (its team or membership is gone)…"
plan_required The token's team is not on a paid plan. "The DrawSQL API requires a paid plan. Upgrade the team "…" to restore access."

A token sees the diagrams its user can see in the token's team. It reads the same diagrams as the REST API.

Rate limits

Limit Applies to Over the limit
20 requests / minute, per IP Every request to /mcp, including initialize and tools/list HTTP 429 with a Retry-After header
10 calls / minute, per IP visualize_schema Tool error rate_limited: "Too many visualize_schema calls. Try again in N seconds."
10 calls / minute, per token, for each tool create_diagram and propose_diagram_changes, counted separately Tool error rate_limited: "Too many create_diagram calls. Try again in N seconds."

The read tools have no limit of their own beyond the 20 requests a minute on the endpoint. The x-ratelimit-* response headers describe the endpoint limit, not the tool limits.

Call order

  • Read a diagram: list_diagrams → get_schema. Add get_diagram_link when you need a URL to cite.
  • Show a schema you have as a diagram, with no account: visualize_schema.
  • Change an existing diagram: list_diagrams → get_schema → get_driver_rules → propose_diagram_changes → get_proposal_status.
  • Create a diagram: get_driver_rules (when you send a patch) → create_diagram → get_diagram_link until the status is ready → get_schema.

visualize_schema

Turns SQL DDL or a DrawSQL schema patch into an editable diagram and returns a drawsql.app/draw link.

Auth: none. REST twin: none.

Inputs. Send exactly one of ddl and schema.

Name Type Required Limits
ddl string Yes, unless schema is set SQL CREATE TABLE and ALTER TABLE statements. Up to 200,000 bytes.
schema string Yes, unless ddl is set A schema patch encoded as a JSON string. Up to 500,000 bytes. Omit deletions: every call makes a new diagram.
driver string No mysql, pgsql, or sqlsrv. Defaults to mysql.

Output. The link, then a summary: driver and counts of tables, columns, and relationships, plus groups, sticky notes, and indexes when there are any. A note follows when the input had more than 20 tables (the link opens the first 20) or when a column type was mapped to the driver's nearest type.

The link needs no account. A link nobody opens expires after 30 days. Opening it extends the expiry to one year from that view.

Errors

Code When The agent reads
invalid_input Neither or both of ddl and schema, or a value that is not a string. "Received both ddl and schema. Provide exactly one."
invalid_driver driver is not a supported value. "The driver value is not supported. Use one of: mysql, pgsql, sqlsrv…"
payload_too_large ddl over 200KB, or schema over 500KB. "The SQL is too large (max 200KB). Trim it and try again."
invalid_json schema is not valid JSON. "The schema value is not valid JSON."
no_tables The DDL or patch has no tables. "No tables were found in the SQL…"
invalid_schema The patch breaks the format. Every problem is listed in one reply, each naming its field. "Invalid schema patch: tables[0].name has leading or trailing whitespace. Send the exact text."
parse_failed The SQL could not be parsed. "Could not parse the SQL. Check the DDL syntax and try again."
rate_limited More than 10 calls in a minute from one IP. "Too many visualize_schema calls. Try again in N seconds."

Example

{
  "name": "visualize_schema",
  "arguments": {
    "driver": "pgsql",
    "schema": "{\"tables\":[{\"name\":\"users\",\"columns\":[{\"name\":\"id\",\"type\":\"bigint\",\"is_primary_key\":true},{\"name\":\"email\",\"type\":\"varchar\"}]},{\"name\":\"orders\",\"columns\":[{\"name\":\"id\",\"type\":\"bigint\",\"is_primary_key\":true},{\"name\":\"user_id\",\"type\":\"bigint\"},{\"name\":\"total\",\"type\":\"decimal\"}]}],\"relationships\":[{\"type\":\"one-to-many\",\"source_table\":\"users\",\"source_column\":\"id\",\"target_table\":\"orders\",\"target_column\":\"user_id\"}]}"
  }
}
Your diagram is ready: https://drawsql.app/draw?t=6ce7d8c1-3b55-4c3f-b075-e12330536714&utm_source=mcp

Open the link to view, edit, share, or export the diagram. No account is required.

**Summary**
- Driver: pgsql
- Tables: 2
- Columns: 5
- Relationships: 1

Rate limit: 10 calls a minute per IP.

Annotations

Hint Value Why
readOnlyHint false (not sent) It stores the schema and creates a new link.
destructiveHint false It only adds a new link; nothing that exists is changed or removed.
openWorldHint false It reaches only DrawSQL, never a third-party system.

Call order: use it whenever the agent can see a schema the user wants as a diagram. It needs nothing first.

list_diagrams

Lists the diagrams visible to the token, newest first.

Auth: bearer token. REST twin: GET /v1/diagrams.

Inputs

Name Type Required Limits
limit integer No 1–100; values outside the range are clamped. Defaults to 25.
cursor string No The cursor from a previous reply. Omit it for the first page.

Output. The team name and the number of diagrams on this page, then one line per diagram: name, table count, status (ready, importing, or failed with its error code), id (the diagram's uuid), and URL. When more pages exist, the last line gives the cursor for the next one. Names are flattened to one line and their Markdown is escaped.

Errors

Code When The agent reads
invalid_token, plan_required See Authentication.
invalid_cursor The cursor was not issued by this tool. "The cursor is not one this tool issued. Omit it to start from the first page."

Example

{ "name": "list_diagrams", "arguments": { "limit": 25 } }
**Acme** — 1 diagram visible to this token:
- **Orders service** — 2 tables — status: ready — id: `030c01ac-2b43-409f-83e8-85d1e38b311e` — https://drawsql.app/teams/acme/diagrams/orders-service

Rate limit: the endpoint limit only.

Annotations

Hint Value Why
readOnlyHint true It only reads diagram metadata.
destructiveHint not sent Clients ignore it on a read-only tool.
openWorldHint false It reads only DrawSQL.

Call order: call it first. The id it returns is the diagram input of get_schema and get_diagram_link. It is also the first step before propose_diagram_changes.

get_schema

Returns a diagram's schema as compact Markdown: tables, columns, types, keys, relationships, groups, indexes, and notes.

Auth: bearer token. REST twin: GET /v1/diagrams/{uuid}/schema?format=ai, which returns the same text.

Inputs

Name Type Required Limits
diagram string Yes The diagram's id (uuid) from list_diagrams.
level string No detailed (types and constraints, the default) or simple (column names only).

Output. The schema in the AI Schema Format. At detailed, columns are NOT NULL unless marked nullable. This is the same text as the editor's Take to your AI.

If the diagram's live editing session holds edits that are not saved yet, the tool saves them first, the same way autosave does, so it reads the current diagram.

Errors

Code When The agent reads
invalid_token, plan_required See Authentication.
invalid_input level is not simple or detailed. "level must be one of: simple, detailed."
not_found The id is unknown, malformed, or not visible to the token. All three read the same. "No diagram with that id is visible to this token. Use list_diagrams to see what is."
diagram_not_ready The diagram is still importing. "diagram_not_ready: this diagram is still importing. Poll get_diagram_link until status is ready."

Example

{ "name": "get_schema", "arguments": { "diagram": "030c01ac-2b43-409f-83e8-85d1e38b311e" } }
# Schema: Orders service
Database: pgsql
Tables: 2
Columns are NOT NULL unless marked nullable.

## users
id: bigint PK
email: varchar

## orders
id: bigint PK
user_id: bigint FK
total: decimal

## Relationships
users.id → orders.user_id (one-to-many)

Rate limit: the endpoint limit only.

Annotations

Hint Value Why
readOnlyHint false (not sent) It can save the diagram's unsaved live edits before it reads.
destructiveHint false That save stores the diagram as people left it; it never removes or changes their work.
openWorldHint false It reads only DrawSQL.

idempotentHint is true: once the save has run, a repeat call with the same arguments writes nothing.

Call order: after list_diagrams. Read it before writing a query or a migration against the schema. Read it before propose_diagram_changes too, so the patch names tables and columns that exist.

Returns a diagram's canonical URL and embed URL, to cite or share.

Auth: bearer token. REST twin: GET /v1/diagrams/{uuid}.

Inputs

Name Type Required Limits
diagram string Yes The diagram's id (uuid) from list_diagrams.

Output. The diagram name, its URL, its embed URL, and its status: ready, importing, or failed with an error code.

Errors

Code When The agent reads
invalid_token, plan_required See Authentication.
not_found The id is unknown, malformed, or not visible to the token. "No diagram with that id is visible to this token. Use list_diagrams to see what is."

Example

{ "name": "get_diagram_link", "arguments": { "diagram": "030c01ac-2b43-409f-83e8-85d1e38b311e" } }
**Orders service**
- URL: https://drawsql.app/teams/acme/diagrams/orders-service
- Embed URL: https://drawsql.app/teams/acme/diagrams/orders-service/embed
- Status: ready

Rate limit: the endpoint limit only.

Annotations

Hint Value Why
readOnlyHint true It only reads diagram metadata.
destructiveHint not sent Clients ignore it on a read-only tool.
openWorldHint false It reads only DrawSQL.

Call order: after list_diagrams, whenever the answer should link to the diagram. After create_diagram returns importing, call it every 5 seconds until the status is ready or failed.

get_driver_rules

Returns the rules for writing a schema patch for one driver: its data types, the patch format, the size limits, and the call order.

Auth: bearer token. REST twin: GET /v1/data-types?driver= and GET /v1/schema-patch-contract.

Inputs

Name Type Required Limits
driver string Yes mysql, pgsql, or sqlsrv. Use the driver of the diagram you are changing.

Output. Three Markdown sections:

  • Data types: one line per type the driver accepts, with its params, its cross-driver family, and its aliases. It is the same list as GET /v1/data-types.
  • Patch format: every section of the patch and the fields it takes, the relationship types, the size limits, which tool accepts positions and sizes, and how retries behave.
  • Call order: the five steps for a change.

Errors

Code When The agent reads
invalid_token, plan_required See Authentication.
invalid_request driver is missing or not supported. "invalid_request: driver must be one of: mysql, pgsql, sqlsrv."

Example

{ "name": "get_driver_rules", "arguments": { "driver": "pgsql" } }
## Data types (pgsql)
- bigint · family: bigInteger · aliases: int8
- bigserial · family: bigSerialPgsql
- boolean · family: boolean · aliases: bool
…
- varchar (params: length) · family: string · aliases: character varying

## Patch format
Top-level sections and the fields each documents:
- `strategy`: merge or additive
- `tables[]`: name, old_name, comment, parent_uuid, parent_name, left, top, columns, indexes
…
- Size limits: `ddl` ≤ 200KB, `schema` ≤ 500KB.

## Call order
`list_diagrams → get_schema → get_driver_rules → propose_diagram_changes → get_proposal_status`
…

Rate limit: the endpoint limit only.

Annotations

Hint Value Why
readOnlyHint true It reads the data-type catalog and the patch format.
destructiveHint not sent Clients ignore it on a read-only tool.
openWorldHint false It reads only DrawSQL.

idempotentHint is true: the same driver returns the same rules until DrawSQL ships new types.

Call order: after get_schema, before propose_diagram_changes or a create_diagram call that sends a patch.

get_proposal_status

Returns where a proposal stands: pending, applied, declined, or expired.

Auth: bearer token; read access is enough. REST twin: GET /v1/proposals/{uuid}.

Inputs

Name Type Required Limits
uuid string Yes The proposal uuid that propose_diagram_changes returned.

Output. One label: value line per field that has a value: state, opened, applied, applied_version (the uuid of the version the apply created), declined, decline_reason, and expires. Times are ISO 8601. A pending proposal adds a line asking the agent to hand the user the review link and poll again. An expired one adds a line saying an editor can reopen it.

A pending proposal past its expiry reads as expired at once.

Errors

Code When The agent reads
invalid_token, plan_required See Authentication.
not_found The uuid is unknown, or the proposal is on a diagram the token cannot see. Both read the same. "No proposal with that uuid is visible to this token."

Example

{ "name": "get_proposal_status", "arguments": { "uuid": "8b404a64-9a03-440b-9e33-7deb23d2286c" } }
state: pending
expires: 2026-10-31T05:58:54+00:00

Ask the user to open the review link; poll again for the outcome.

Rate limit: the endpoint limit only.

Annotations

Hint Value Why
readOnlyHint true It only reads the proposal.
destructiveHint not sent Clients ignore it on a read-only tool.
openWorldHint false It reads only DrawSQL.

idempotentHint is true: polling never changes the proposal.

Call order: last, after propose_diagram_changes. A declined proposal is closed: act on decline_reason by sending a new proposal.

create_diagram

Creates a private diagram in the token's team from SQL DDL or a schema patch.

Auth: a token with Read and write access. REST twin: POST /v1/diagrams.

Inputs. Send exactly one of ddl and schema.

Name Type Required Limits
ddl string Yes, unless schema is set SQL CREATE TABLE and ALTER TABLE statements. Up to 200,000 bytes.
schema string Yes, unless ddl is set A schema patch encoded as a JSON object string. Up to 500,000 bytes. Positions and sizes (left, top, width, height) are rejected: DrawSQL computes the layout.
name string No Up to 255 characters. Defaults to Untitled.
driver string No mysql, pgsql, or sqlsrv. Defaults to mysql.

Output. The diagram's URL and uuid, then a summary: driver and counts of tables, columns, and relationships, plus groups, sticky notes, and indexes when there are any. Ignored patch fields come back as notes.

The call returns within 15 seconds. A DDL import still running then comes back as Diagram created, import in progress, with a line to poll get_diagram_link in 5 seconds; get_schema fails with diagram_not_ready until the import is ready. An import that cannot finish reports Diagram created but the import failed (code): …. The same call repeated within 120 seconds (same token, name, driver, and payload) returns the diagram it already made, starting with Already created N seconds ago.

The team's plan sets how many tables a diagram may hold and how many private diagrams the team may have.

Errors

Code When The agent reads
invalid_token, plan_required See Authentication.
insufficient_scope The token has no write access. Usually the tool is not listed at all; this shows when a client calls it from an outdated list. "insufficient_scope: this token cannot write. Mint a token with the write ability."
not_available Writes are switched off. "This tool is not available right now. Refresh the tool list."
rate_limited More than 10 calls in a minute on this token. "Too many create_diagram calls. Try again in N seconds."
forbidden The token's user cannot create diagrams in the token's team. "forbidden: this token's user cannot create diagrams in the token's team."
invalid_request Neither or both inputs, an empty ddl, a schema that is not a JSON object, an unsupported driver, or a name over 255 characters. "invalid_request: Send exactly one of ddl or schema."
payload_too_large ddl over 200KB, or schema over 500KB. "payload_too_large: The schema is too large (max 500KB)."
unsupported_field The patch carries positions or sizes. "unsupported_field: Positions and sizes are not accepted when creating a diagram; the layout is computed. Remove: tables[0].left."
invalid_schema The patch breaks the format. "invalid_schema: Invalid schema patch: …"
no_tables The patch has no tables. "no_tables: The schema patch has no tables. Include at least one table."
plan_limit The patch has more tables than the plan allows per diagram, or the team has no private diagrams left. "plan_limit: The schema has N tables; this team's plan allows M per diagram."

A DDL import that fails after the call returns does not produce a tool error. The diagram's status becomes failed with one of parse_failed, no_tables, plan_limit, or import_failed, and list_diagrams and get_diagram_link show it.

Example

{
  "name": "create_diagram",
  "arguments": {
    "name": "Orders service",
    "driver": "pgsql",
    "schema": "{\"tables\":[{\"name\":\"users\",\"columns\":[{\"name\":\"id\",\"type\":\"bigint\",\"is_primary_key\":true},{\"name\":\"email\",\"type\":\"varchar\"}]},{\"name\":\"orders\",\"columns\":[{\"name\":\"id\",\"type\":\"bigint\",\"is_primary_key\":true},{\"name\":\"user_id\",\"type\":\"bigint\"},{\"name\":\"total\",\"type\":\"decimal\"}]}],\"relationships\":[{\"type\":\"one-to-many\",\"source_table\":\"users\",\"source_column\":\"id\",\"target_table\":\"orders\",\"target_column\":\"user_id\"}]}"
  }
}
Diagram created: https://drawsql.app/teams/acme/diagrams/orders-service
uuid: 030c01ac-2b43-409f-83e8-85d1e38b311e

**Summary**
- Driver: pgsql
- Tables: 2
- Columns: 5
- Relationships: 1

Rate limit: 10 calls a minute per token.

Annotations

Hint Value Why
readOnlyHint false (not sent) It creates a diagram.
destructiveHint false It only adds a new diagram; nothing that exists is overwritten or removed.
openWorldHint false It writes only to DrawSQL.

idempotentHint is false: an identical call within 120 seconds returns the same diagram, but after that a repeat creates another one.

Call order: call get_driver_rules first when you send a patch. After an importing reply, poll get_diagram_link, then read the result with get_schema.

propose_diagram_changes

Proposes a schema patch to an existing diagram. Nothing changes until an editor reviews the proposal in DrawSQL and applies it.

Auth: a token with Read and write access, whose user can edit the diagram. REST twin: POST /v1/diagrams/{uuid}/proposals.

Inputs

Name Type Required Limits
diagram string Yes The diagram's id (uuid) from list_diagrams.
schema string Yes A schema patch encoded as a JSON object string. Up to 500,000 bytes. The full format applies, including deletions, renames, groups, sticky notes, and positions and sizes.
title string Yes A short title, like a pull request title. 1–100 characters.
message string Yes Why the change is needed. 1–500 characters. The reviewer reads it before deciding.

Output. The review link, the proposal's uuid, its expiry (30 days), and counts of the tables, columns, and relationships the patch names, plus groups, sticky notes, and deletions when there are any. A last line asks the agent to hand the user the link and poll get_proposal_status.

The patch is checked for shape when you send it. The reviewer's editor applies it to the diagram as it is at review time. See Reviewing a proposal.

Errors

Code When The agent reads
invalid_token, plan_required See Authentication.
insufficient_scope The token has no write access (only from an outdated tool list). "insufficient_scope: this token cannot write. Mint a token with the write ability."
not_available Writes are switched off. "This tool is not available right now. Refresh the tool list."
rate_limited More than 10 calls in a minute on this token. "Too many propose_diagram_changes calls. Try again in N seconds."
not_found The diagram id is unknown, malformed, or not visible to the token. "No diagram with that id is visible to this token. Use list_diagrams to see what is."
invalid_request schema is missing or not a JSON object, or title or message is missing, empty, or too long. "invalid_request: title is required: a string of 1 to 100 characters."
payload_too_large schema over 500KB. "payload_too_large: The schema is too large (max 500KB)."
editor_required The token's user can view the diagram but not edit it. "editor_required: Proposals need an editor: this token's user can view this diagram but cannot edit it."
diagram_not_ready The diagram is still importing. "diagram_not_ready: This diagram is still importing…"
invalid_schema The patch breaks the format. "invalid_schema: Invalid schema patch: …"

Example

{
  "name": "propose_diagram_changes",
  "arguments": {
    "diagram": "030c01ac-2b43-409f-83e8-85d1e38b311e",
    "title": "Add order notes",
    "message": "Support needs free-text notes on orders.",
    "schema": "{\"tables\":[{\"name\":\"orders\",\"columns\":[{\"name\":\"notes\",\"type\":\"text\",\"is_nullable\":true}]}]}"
  }
}
Proposal created for review: https://drawsql.app/teams/acme/diagrams/orders-service?proposal=8b404a64-9a03-440b-9e33-7deb23d2286c
uuid: 8b404a64-9a03-440b-9e33-7deb23d2286c
expires: 2026-10-31T05:58:54+00:00

**Summary**
- Tables: 1
- Columns: 1
- Relationships: 0

Ask the user to open the link to review and apply the changes. Nothing changes until an editor applies it. Poll `get_proposal_status` with the uuid for the outcome.

Rate limit: 10 calls a minute per token.

Annotations

Hint Value Why
readOnlyHint false (not sent) It stores a proposal.
destructiveHint false Nothing is applied without an editor, even when the patch deletes tables.
openWorldHint false It writes only to DrawSQL.

idempotentHint is false: every call creates a new proposal, so retry only a call that returned no uuid.

Call order: after list_diagrams, get_schema, and get_driver_rules. Then hand the user the review link and poll get_proposal_status with the uuid.