platypus-db
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
PlatypusDB gives access to the database connections the user saved in the PlatypusDB app. Start with list_connections, then explore with list_schemas, list_objects, describe_table, get_ddl, get_er_diagram, compare_schemas and search_objects, look at a table's first rows with sample_rows, profile its columns with profile_table (sensitive columns give counts only), query with run_query (next_page reads the rest of a cut result; query_across_databases joins tables of several connections) and read a statement's plan with explain, and ask estimate_change what a change would show the user before it runs (nothing runs); server_activity and top_queries read what the server does: one statement per call, with a row limit, a byte limit and a timeout. To hand the user SQL to review and run by hand (a change the access does not allow, a long script), use propose_sql; to hand the user rows to change in a table, use propose_edits: they open in its data viewer as pending edits to save or discard. Each connection has an agent access set by the user: read_only connections run only statements that change nothing, inside a read-only transaction; read_write connections also accept changes, which commit at once. Production connections are always read-only. Passwords never reach you. While the PlatypusDB app is open, list_open_sessions shows what the user has open there, and changes may wait for the user to allow them in the app; when they say "this query", "what I selected" or "the result I see", get_user_context asks them to share it. list_scripts and read_script show the scripts the user saved, search_history the statements run before, to learn how the user queries the data. server_activity (sessions, running statements, locks) and top_queries (the statements that cost the server most time) show what the server is doing, read-only, with the statements' values masked. Connections, schemas and tables are also MCP resources (platypus:////), for clients that attach them as context.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| prompts | {} |
| resources | {
"subscribe": true,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| compare_schemasA | Compares two schemas, of one connection or of two connections of the same kind of database, as the PlatypusDB schema compare does: the differences (tables, columns, indexes, foreign keys and constraints added, dropped or changed) and the migration script that makes |
| describe_tableA | Describes a table or view: columns (type, nullable, default, primary key, comment, enum values), indexes, foreign keys, other constraints and the foreign keys of other tables that point at it. Also the notes, tags and sensitive marks the user set in PlatypusDB (note, tags, sensitive: true or false, never values), when there are any. |
| estimate_changeA | Dry run of a change: returns, without running anything, what the confirmation dialog would show the user for one SQL statement: the rows the database expects to change (estimated_rows) and its plan, the Safety checks that would ask or refuse (safety_checks), and whether the user is asked in the app (asks_the_user) and the change would run (would_run). A statement the connection's access refuses answers outcome=refused with the reason; one that changes nothing answers outcome=not_a_change. A database without plans answers with no estimate and says so. Use it to correct a statement before run_query asks the user. |
| explainA | Returns the plan of one SQL statement: its steps as an indented tree with cost, estimated rows and, with analyze=true, actual rows and times (or JSON with format=json), then index suggestions for filtered full scans of large tables. Without analyze the statement does not run. With analyze it runs and what it changes is rolled back; on read_only connections only statements that change nothing are explained, and analyze needs PostgreSQL, MySQL, MariaDB or SQLite. max_bytes (default 32768) and timeout_seconds (default 30) work as in run_query. |
| get_ddlB | Returns the CREATE statement of a table, view, function, trigger or other object. |
| get_er_diagramA | Returns a Mermaid erDiagram of a schema's tables (columns, primary keys) and the foreign keys between them, as text. Without |
| get_user_contextA | Asks the user to share what they are looking at in the PlatypusDB app: the text of the active editor tab (editor), the part they selected (selection) and the result their grid shows (result: columns and rows). Use it when the user refers to something on their screen: "this query", "what I selected", "the result I see". Nothing is shared unless the user allows it in the app, each time or for your whole session; they can refuse, with a reason you get. parts limits what you ask for (all three by default). Answers connection, tab (its title) and the parts shared; the editor and selection are cut at 64 KiB, the result at 100 rows and 32 KiB (truncated says so). A tab on a connection that is not open to agents is not shared. Needs the app open; read-only: nothing runs. |
| list_connectionsA | Lists the database connections saved in PlatypusDB that agents may use: name, id, driver, type (dev, test, prod), database and agent_access (read_only or read_write). Never shows hosts, users or passwords. |
| list_objectsA | Lists the tables, views, sequences, functions, procedures, triggers and types of a schema, with their kind, comment and estimated rows: a list of up to 500 objects (limit raises it to 2000). A schema with more returns {objects, truncated: true, total, offset, next_offset}: call again with offset=next_offset for the next page, or use search_objects to find names. |
| list_open_sessionsA | Lists the sessions open in the PlatypusDB app, when it is open: their connection, the database when it is not the connection's own, purpose ( |
| list_schemasA | Lists the schemas of a connection (databases in MySQL and MariaDB, |
| list_scriptsA | Lists the SQL scripts the user saved in PlatypusDB: path (relative to the project, with |
| next_pageA | Reads the next rows of a result that run_query cut at max_rows or max_bytes, from the cursor it returned, instead of running the statement again: the pages come from the rows read with the first one (up to 10000 more rows, 4 MB or 250 ms of reading; the answer says when the result has more than that), so they do not change if the data does. Same format, max_rows (default 100) and max_bytes as run_query, with the connection's limits and calls per minute; sensitive columns stay masked as in the first page. A cursor is kept 5 minutes after its last use and belongs to this session; an unknown, expired or another session's cursor is refused. |
| profile_tableA | Profiles the columns of a table or view from a sample of its rows (the first sample_rows, default 10000, up to 100000; no order is implied): per column NULLs, distinct values, empty texts, minimum and maximum, the most frequent values, patterns (emails, dates, numbers stored as text...) and, for numbers, their spread. Sensitive columns (as in results) give counts only: no value of any kind. Read-only, within the connection's limits; max_bytes and timeout_seconds work as in run_query. |
| propose_editsA | Proposes rows to change in a table: PlatypusDB opens the table's data viewer with them as pending edits (new rows, changed cells, rows marked for deletion) that the user reviews, saves or discards (now if the app is open, else when it starts). Nothing is written here, whatever the connection's agent access. inserts: objects of column to value. updates: {key, set}, key naming a row by exactly the columns of a primary or unique key. deletes: objects naming rows by such a key. A value is a string, number, boolean or null (no arrays or objects); at most 500 rows and 1 MiB in all. The table needs a primary or unique key. On MongoDB the table is a collection (not a view) and the key is _id alone, read by the type of the collection's _id: an ObjectId as its 24 hex digits. Redis, Elasticsearch and Cassandra, read-only connections and those that forbid editing data are refused. title names the tab. |
| propose_sqlA | Proposes SQL to the user: PlatypusDB opens it in a new editor tab on the connection (now if the app is open, else when it starts), where the user reviews, edits and runs it by hand. Nothing runs here, whatever the connection's agent access: use it for changes the user should check, or that read_only access does not allow. title names the tab. |
| query_across_databasesA | Runs one read-only DuckDB statement over tables of several connections: each source (connection, schema, table, optional name) is copied, up to source_rows rows (default 10000, up to 100000) and within that connection's limits, into a DuckDB of this call, where the statement joins them by name. Every connection must be open to agents; the statement runs only on the copies, cannot write to a source and reads no file nor URL. Values of sensitive columns are masked before they are copied (unless the user shows them for that connection): all values of such a column are equal, so do not join on one. A source copied in part is said so. Use DuckDB's SQL. Same result format and limits as run_query. |
| read_scriptA | Returns the text of a script the user saved in PlatypusDB, by the path list_scripts shows, with the connection it is linked to. At most 256 KiB: a longer script is cut, and the answer says so (truncated). A script linked to a connection agents may not use is refused. Read-only: nothing is run or changed. |
| run_queryA | Runs one SQL statement on a connection and returns its rows as an aligned text table (or JSON with format=json, where integers beyond 2^53 are strings so that no JSON parser rounds them), saying when rows or long values were left out. In the text table SQL NULL is NULL, and a text that reads NULL shows quoted, 'NULL'. Defaults: 100 rows, 32768 bytes, 30 s timeout; max_rows, max_bytes and timeout_seconds raise them up to 10000 rows, 1048576 bytes and 300 s. On read_only connections only statements that change nothing run, in a read-only transaction; on read_write connections changes commit at once, and UPDATE or DELETE without WHERE is refused unless the user's safety settings allow it. Use the database's own SQL dialect. A result cut by max_rows or max_bytes returns a |
| sample_rowsA | Returns the first rows of a table, view, MongoDB collection or search index (default 20 rows), as run_query returns them: an aligned text table, or JSON with format=json. max_rows, max_bytes and timeout_seconds work as in run_query. The rows come in the order the database reads them: no order is implied. |
| search_historyA | Searches the history of statements run in PlatypusDB, newest first, on the connections agents may use: connection, sql, started_at (UTC, RFC 3339), duration_ms, rows, status (ok, error or cancelled), error and origin ( |
| search_objectsA | Finds objects of a connection whose name contains a text, ignoring case; where the database supports it, also objects with such a column or in whose source the text appears; also objects whose comment or the user's notes contain it (matched comment or note), and #tag finds the objects the user tagged. At most 200 matches. |
| server_activityA | What the database server is doing now: its sessions (user, database, client, state, the statement running and for how long, what it waits for and the sessions blocking it) and the locks held or waited for, as in the PlatypusDB admin tab; sessions that wait or run first, 50 by default (limit, up to 200). The statements are other people's: credentials and the values of sensitive columns are masked, and long ones cut at 500 characters. PostgreSQL, MySQL, MariaDB and SQL Server; read-only: nothing is cancelled or ended. A missing privilege is said so. |
| top_queriesA | The statements that took the server most time, the costliest first, from its own statistics (pg_stat_statements, performance_schema, Query Store): the statement with its values replaced as the server writes them, calls, total, mean and max seconds, rows, user and database. 20 by default (limit, up to 100). Credentials and the values of sensitive columns are masked, long statements cut at 500 characters. PostgreSQL, MySQL, MariaDB and SQL Server; read-only. Says so when the statistics are not enabled (pg_stat_statements not installed) or the user may not read them. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| explain-query | Reads the plan of a statement, finds what makes it slow and proposes a better one. |
| slowest-queries | Reads what costs the server most time and suggests what to fix first. |
| write-migration | Writes the statements (and how to undo them) for a change to the schema, checks them and hands them over without running them. |
| document-table | Writes a description of a table: columns, keys, relations, what the data looks like. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 24 tools
Most tools target clearly distinct resources or actions, and the descriptions draw sharp boundaries between similar-sounding tools such as explain vs. estimate_change and run_query vs. sample_rows. A few pairs still require careful reading, but an agent can generally select correctly.
The set is overwhelmingly snake_case with a verb_noun pattern (list_objects, describe_table, propose_sql, search_history). Minor deviations like top_queries, next_page, server_activity, and explain are readable but break the pattern slightly.
At 24 tools, the surface is heavy for a database MCP server and sits at the upper end of the borderline range. Each tool appears purposeful, but the breadth of schema, query, admin, scripting, and proposal features makes the set large enough to feel burdensome.
The tool set covers connection discovery, schema and object introspection, querying, pagination, explain/estimate, profiling, sampling, cross-database queries, SQL and row-edit proposals, scripts, history, sessions, server activity, and schema comparison. No obvious lifecycle or workflow gap remains for the stated database-assistant purpose.