The NeoSQL MCP server (neosql-mcp) offers 12 tools to external AI clients such as Claude Code. This page collects, in tables, what each tool does, what it takes, whether it changes the DB or files, and whether NeoSQL asks separately. What MCP is and which safeguards apply are described in AI and MCP, and how to register it with a client in MCP client setup.
Tools at a glance
| Tool | What it does | What it changes | What NeoSQL asks |
|---|---|---|---|
ping | Checks the connection. Returns pong | Nothing | Nothing |
get-mcp-session-id | Returns the ID of this MCP session | Nothing | Nothing |
get-context-help | Explains the rules for choosing the target project and connection | Nothing | Nothing |
list-projects | Lists the projects that can be opened on this device | Nothing | Nothing |
create-project | Creates a new local project | Project | A creation confirmation dialog |
list-connections | Lists the connections and schemas allowed for AI | Nothing | Nothing |
list-tables | Lists tables (search by name or description) | Nothing | Nothing |
get-table-details | Columns, indexes, foreign keys and constraints of tables | Nothing | Nothing |
erd-create-tables | Designs new tables in an ERD | ERD (the DB is unchanged) | Nothing |
erd-modify-tables | Modifies tables in an ERD | ERD (the DB is unchanged) | Nothing |
execute-query | Runs SQL | DB | A confirmation dialog, depending on the protection mode and policy |
generate-code | Generates source files with the project's template packs | Files in the project folder | Nothing |
ping, get-mcp-session-id and get-context-help are answered inside the MCP server without calling the desktop app. The desktop app handles the rest.
Arguments that choose the target
Tools that work with projects and DBs also take the arguments below. All of them can be omitted.
| Argument | Tools | Contents |
|---|---|---|
projectId | All tools except list-projects, create-project and the ping group | The target project, as returned by list-projects or create-project. If that project is not open, the desktop app opens it |
connectionId, database, schema | list-tables, get-table-details, erd-create-tables, erd-modify-tables, execute-query, generate-code | The target connection and location. Give all three together or omit all of them. database is null for DBMSs without that level |
- The target project is decided by the
projectIdargument, then--project-idin the client configuration, then the project open in the desktop app. If the configuration has--project-idand you pass a differentprojectId, nothing runs and an error is returned. - When the location is omitted, the one chosen with the Default option in Project AI settings is used. It is an error if none or several are chosen. In account projects, the default of a public connection comes before that of a private one.
- A call that points at a connection whose Enabled option is off is refused.
list-connectionsleaves such connections out.
Connection and help
ping
No arguments. It only checks that the MCP server is alive. It does not check the link to the desktop app; to check the app as well, call list-projects.
get-mcp-session-id
No arguments. Returns the session ID created when the MCP server started. With this ID, the SQL Editor tabs and ERDs whose names start with MCP: are kept separate per session.
get-context-help
No arguments. Returns the order in which the target project is chosen, the rule of giving the three location arguments together, the tool for finding connections (list-connections), and an example client configuration (npx -y neosql-mcp).
Projects
list-projects
No arguments, and no project needs to be open. For each project it returns projectId, the name, the type (local or account), when it was last opened and whether it is open now. When you are not signed in, only local projects appear, together with a marker (signed_out) saying account projects were left out. Suspended projects do not appear.
create-project
| Argument | Contents |
|---|---|
name | The project name. Leading and trailing spaces are removed; up to 100 characters |
dataSource | The name of the DBMS to design for (such as PostgreSQL or MySQL), case-insensitive. An unaccepted name returns an error listing the accepted names |
- The Confirm MCP Project Creation dialog appears in the desktop app, and the project is created only if the user agrees. With no answer within 45 seconds, nothing is created.
- What it creates is a local project containing one design-only connection (without DB credentials) set as the default location. You do not need to be signed in.
- If the open project has unsaved changes, nothing is created. Once created, the open project is closed and the new one is opened.
- It cannot be used when the client configuration has
--project-id(project-scoped setup).
Reading the schema
list-connections
The only argument is projectId. For each connection that allows AI and has at least one schema selected, it returns connectionId, the name, the description, the DBMS and its version, whether it is design-only, the connection profile (environment and protection mode), and the available Databases and Schemas with whether each location auto-commits. It does not reveal whether DDL runs without asking.
list-tables
| Argument | Contents |
|---|---|
search | Text contained in table names or descriptions, case-insensitive. Omit it to list all |
It searches the list NeoSQL has already loaded, so no SQL is sent to the DB. For each table it returns the name, type and description.
get-table-details
| Argument | Contents |
|---|---|
tableNames | A list of table names (a list even for one). Names must match exactly, including case |
It returns the columns, indexes, foreign keys and constraints of each table and collects names it could not find in notFound. Tables not loaded yet have their metadata read from the DB at this point.
ERD design
These two tools save only to the ERD and the project's design and do not change the DB. The results appear in an ERD tab whose name starts with MCP:; one such ERD is created per MCP session and location (connection, Database and Schema). They also work on design-only connections. How to apply the design to the DB is described in ERDs and the real database.
erd-create-tables
| Argument | Contents |
|---|---|
tableDefinitions | The list of tables to create. For each table, give all of name, remarks, columns, primaryKeys, importedKeys (foreign keys), indexes and constraints |
For each column, give the name, type, size, decimalDigits, nullable, autoIncrement, defaultValue and remarks. Tables whose names already exist are skipped.
erd-modify-tables
| Argument | Contents |
|---|---|
alterations | The list of tables to modify. For each table, give tableName and the operations below |
| Operation | What it can do |
|---|---|
newTableName | Rename the table |
remarksOperation | Change the table description (optional) |
primaryKeyOperations | Add or remove PK columns (optional) |
columnOperations | Column ADD, DROP, MODIFY, RENAME |
indexOperations | Index ADD, DROP |
foreignKeyOperations | Foreign key ADD, DROP |
constraintOperations | UNIQUE, CHECK and EXCLUSION constraint ADD, DROP |
Running SQL
execute-query
| Argument | Contents |
|---|---|
sql | The SQL to run |
- It cannot be used on design-only connections.
- The SQL is kept in, and runs in, an
MCP:SQL Editor tab created per MCP session and location. - Query results return up to 200 rows. If the plan's row limit is lower, that value applies. Truncation is reported with
truncated.
Each statement you send is checked in the order below. The first matching row from the top applies, and if you send several statements and any one of them is refused, none of them runs. DDL means CREATE, ALTER, DROP, RENAME, TRUNCATE, COMMENT, GRANT, REVOKE and SELECT … INTO.
| Order | Condition | Result |
|---|---|---|
| 1 | DDL from a user restricted by the DDL Restriction permission in an account project | Refused |
| 2 | The connection's protection mode is the Read-only (block non-SELECT) option and the statement is not a query (SELECT, or EXPLAIN of a query) | Refused |
| 3 | The protection mode is the Confirm (DDL + risky DML) option and the statement is DDL or an UPDATE·DELETE without a condition, or it is DDL and the Schema changes option is off | A confirmation dialog (the Confirm MCP DDL Execution dialog or the Confirm MCP SQL Execution dialog) appears in NeoSQL and the statement runs only after the user presses run. With no answer within 45 seconds, it does not run |
| 4 | Otherwise | Runs immediately |
After a statement passes the checks, committing works as follows.
| Case | Result |
|---|---|
| The Data changes option is on | Auto-commits |
| The Data changes option is off | Returns with the transaction left open. Commit or roll back in NeoSQL's MCP: SQL Editor tab |
| DDL is sent while a transaction is open | Does not run, because DDL would commit the open transaction |
Masking of query results exists only in account projects. Columns designated as sensitive are masked according to the user's role, and turning on the Always mask sensitive data option on a connection masks them regardless of role. Masked columns are marked separately in the result. If the masking information cannot be obtained, the query does not run. Local projects have no masking.
Code generation
generate-code
| Argument | Contents |
|---|---|
tableNames | The list of table names to generate code for (a list even for one) |
- It generates files with the template packs added to the project and saves them to the project folder without asking. Depending on the template's install settings, it overwrites existing files or replaces marked spots. It returns the saved file paths, skips and failures rather than the generated code.
- If the project folder (Location), template packs or required variables are missing, it creates no files and returns
needs-configuration. Where to fill them in is described in Generating source code. - The values and functions available in templates are the same as in Template syntax.
Things to keep in mind
- If the external client is set to approve tools automatically, calls arrive without user confirmation. NeoSQL itself asks only for
create-projectand, depending on the protection mode and policy, forexecute-query. - On a connection without a protection mode, with the Data changes option on, even a DELETE without a condition is auto-committed without asking. For a production DB, set a protection mode or connect with a DB account that has no write permission.
generate-codecan overwrite files without asking. Use it in a folder managed with Git and review the changes afterwards.- Schemas and query results returned to the client may pass through it to the client's model provider.
Related screens
- AI and MCP: how MCP differs from the AI Assistant, the connection policy and the DDL execution checks.
- MCP client setup: the dialog that registers NeoSQL MCP with external AI clients.
- Project AI settings: the dialog that sets use, default, schema change, data change and masking per connection.
- SQL editor: where you see the SQL left in
MCP:tabs and commit or roll back. - ERD canvas: where you view and refine
MCP:ERDs. - Safeguards for production databases: connection protection mode and the dangerous SQL confirmation.
- Column masking: sensitive columns and role-based masking.