# 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](#connect-a-client); the [MCP page](/mcp) 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:

```bash
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:

```bash
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:

```bash
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](/user/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:

```bash
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:

```bash
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:

```json
{
  "mcpServers": {
    "drawsql": {
      "url": "https://drawsql.app/mcp"
    }
  }
}
```

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=drawsql&config=eyJ1cmwiOiJodHRwczovL2RyYXdzcWwuYXBwL21jcCJ9)

### VS Code

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

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

[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22drawsql%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fdrawsql.app%2Fmcp%22%7D)

## 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](/reference/mcp).

## 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

- REST API: `https://api.drawsql.app/v1`, the same token. [Guide](/docs/api), [OpenAPI 3.1](/openapi.yaml).
- Schema patch format: [reference](/reference/schema-patch), [contract JSON](/schema-patch-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](/llms.txt).
- For people: [the MCP page](/mcp) and [the MCP docs](/docs/mcp).
