DrawSQL for agents
Call DrawSQL's hosted MCP endpoint, https://drawsql.app/mcp, from an agent or your own code. This page covers JSON-RPC requests, authentication, tools, call order and limits. Client setup for Claude Code, Codex, Cursor and VS Code is below; the MCP page explains it for people. A Markdown copy is at /agents.md.
Call it from your own runtime
The endpoint speaks JSON-RPC 2.0 over streamable HTTP. Every message is a POST to https://drawsql.app/mcp. The server keeps no session, so there is no session header to carry between calls. A GET returns 405, because the server offers no event stream.
List the tools:
curl -s https://drawsql.app/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Call one:
curl -s https://drawsql.app/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "visualize_schema",
"arguments": {
"ddl": "CREATE TABLE users (id BIGINT PRIMARY KEY, email VARCHAR(255) NOT NULL);",
"driver": "mysql"
}
}
}'
The result is one text block: a drawsql.app/draw link, then the driver and the table, column and relationship counts. It never repeats your table or column names.
Authenticate
Without a token the server lists one tool, visualize_schema.
To read a team's diagrams, send a DrawSQL API token on every request:
curl -s https://drawsql.app/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer <your-token>' \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "list_diagrams",
"arguments": { "limit": 10 }
}
}'
Create the token under Account → API tokens. Tokens are on paid plans, and each token belongs to one team.
Under Access, a Read only token gets the read tools. A Read and write token also lists create_diagram and propose_diagram_changes.
Connect a client
Claude Code
Run this once to make DrawSQL available in every project:
claude mcp add --transport http --scope user drawsql https://drawsql.app/mcp
To limit DrawSQL to the current project, omit --scope user.
Codex
Run this once:
codex mcp add drawsql --url https://drawsql.app/mcp
Cursor
Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all projects:
{
"mcpServers": {
"drawsql": {
"url": "https://drawsql.app/mcp"
}
}
}
VS Code
Add to .vscode/mcp.json in your workspace:
{
"servers": {
"drawsql": {
"type": "http",
"url": "https://drawsql.app/mcp"
}
}
}
Tools
| Tool | Needs | Returns |
|---|---|---|
visualize_schema |
Nothing | A link that opens ddl or a schema patch as an editable diagram, with counts. |
list_diagrams |
Token | The diagrams the token can see: names, uuids, table counts, URLs. Paginated by an opaque cursor. |
get_schema |
Token | A diagram's schema as compact Markdown. level is simple or detailed. |
get_diagram_link |
Token | A diagram's canvas and embed URLs. |
get_driver_rules |
Token | For one driver: its data types, the schema patch format, the size limits and the call order. |
get_proposal_status |
Token | A proposal's state: pending, applied, declined or expired, with the reviewer's reason for a decline. |
create_diagram |
Read and write token | A new private diagram in the token's team, from ddl or a schema patch. |
propose_diagram_changes |
Read and write token | A proposal against an existing diagram, with a review link and the proposal uuid. |
Parameters, examples and errors for each tool are in the MCP tools reference.
Call order
Before you write a query or a migration against a schema the team keeps in DrawSQL:
list_diagramsto find the diagram and itsuuid.get_schemawithlevel: simpleto orient, thendetailedbefore you write DDL.
To change a diagram:
list_diagrams → get_schema → get_driver_rules → propose_diagram_changes → get_proposal_status
propose_diagram_changes does not edit the diagram. It returns a review link. Hand that link to the user, then poll get_proposal_status. An editor applies or declines the proposal in DrawSQL, and a decline can carry a reason for the next attempt.
A diagram is the design a team keeps on purpose. It is not a snapshot of the deployed database. When correctness depends on what is deployed, check the migrations or the database, and tell the user where they differ from the diagram.
Limits
ddlup to 200 KB. Aschemapatch up to 500 KB.- Drivers:
mysql,pgsql,sqlsrv. The default ismysql. visualize_schema: 10 calls a minute per IP address. The link opens the first 20 tables, and the response says when it cut some.- The HTTP transport: 20 requests a minute per IP address, handshake and discovery calls included. The
x-ratelimit-*headers describe this limit, not the tool limits. - A link nobody opens expires after 30 days. Opening it extends the expiry to one year.
- API tokens need a paid plan. A token on a team without one fails with
plan_required. create_diagramandpropose_diagram_changes: 10 calls a minute per token, each.create_diagramanswers within 15 seconds. A SQL import still running comes back asimporting; pollget_diagram_linkuntil it isready. The same request sent again within two minutes returns the diagram it already made.- The plan's table limit applies to created diagrams: 50 tables per diagram on Starter, 100 on Growth, no limit on Large.
- A proposal expires after 30 days.
Other ways in
- REST API:
https://api.drawsql.app/v1, the same token. Guide, OpenAPI 3.1. - Schema patch format: reference, contract JSON.
- No tool call at all: a
https://drawsql.app/draw#ddl=<url-encoded SQL>link opens the same editable diagram. See llms.txt. - For people: the MCP page and the MCP docs.