Docs

For agents and developers

The technical reference: the MCP endpoint, its tools, and the shape of a proposal.

Endpoint

Address: https://jilliondb.com/mcp (streamable HTTP, JSON-RPC 2.0).
Authentication: Authorization: Bearer dbk_… with a key from Settings.
Limits: 240 requests a minute per key, 50 proposals waiting per project.

Tools

list_projects

Lists the JillionDB projects this key can see, with their database engine and table count.

get_schema

Returns the current schema of a project as SQL for its database engine (default) or as JillionDB JSON.

list_issues

Lists design problems in the current schema: missing keys, unindexed relationships, type mismatches and engine limits.

propose_change

Proposes a schema change for the user to review in JillionDB.

get_proposal

Returns a proposal’s status.

list_proposals

Lists recent proposals for a project, newest first.

Proposing a change

Send exactly one of operations or sql, with a one-sentence summary for the reviewer. Prefer operations: they say exactly what changes, so a rename stays a rename. sql is the complete desired schema, and JillionDB works out the difference.

{
  "project_id": "…",
  "summary": "Add a timezone to users so reminders go out at local time",
  "operations": [
    { "op": "add_column", "table": "users",
      "column": { "name": "timezone", "type": "varchar(64)", "nullable": false, "default": "UTC" } }
  ]
}

Operations

Each operation is an object with "op" and the fields below. Names are table and column names as they appear in get_schema.
- create_table: table, columns [{name, type, nullable?, default?, unique?, primary_key?, comment?, references?}], primary_key? [names], comment?
- drop_table: table
- rename_table: table, to
- add_column: table, column {name, type, nullable?, default?, unique?, comment?, references?}
- drop_column: table, column
- rename_column: table, column, to
- alter_column: table, column, type?, nullable?, default?, unique?, comment?
- add_index: table, columns [names], unique?, name?
- drop_index: table, name or columns
- add_foreign_key: table, columns [names], references {table, columns? (defaults to its primary key), on_delete?}
- drop_foreign_key: table, columns or name
- set_primary_key: table, columns
- add_check: table, expression, name?
- drop_check: table, name or expression
- set_comment: table, column?, comment
Types: uuid, text, varchar(n), char(n), smallint, integer, bigint, serial, bigserial, decimal(p,s), float, double, boolean, date, time, timestamp, timestamptz, json, binary, enum('a','b').
Defaults: a value (string, number, true/false), "now", "uuid", "autoincrement", {"value": ...} for literal text that looks like a keyword, or {"sql": "..."} for a raw expression.
references: {table, column?, on_delete?: cascade | restrict | set null | set default | no action}.

After approval

get_proposal returns migration_up and migration_down for the project’s database. Write the up SQL into the project’s migrations exactly as given, and the down SQL as its rollback if your migration tool supports one. If the reviewer edited the proposal, edited_by_reviewer is true.