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. Addget_diagram_linkwhen 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_linkuntil the status isready→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.
get_diagram_link
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.