DrawSQL
.md

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"
    }
  }
}

Add to Cursor

VS Code

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "drawsql": {
      "type": "http",
      "url": "https://drawsql.app/mcp"
    }
  }
}

Install in VS Code

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:

  1. list_diagrams to find the diagram and its uuid.
  2. get_schema with level: simple to orient, then detailed before 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

  • ddl up to 200 KB. A schema patch up to 500 KB.
  • Drivers: mysql, pgsql, sqlsrv. The default is mysql.
  • 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_diagram and propose_diagram_changes: 10 calls a minute per token, each.
  • create_diagram answers within 15 seconds. A SQL import still running comes back as importing; poll get_diagram_link until it is ready. 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