Reference

MCP tools

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

ToolWhat it doesWhat it changesWhat NeoSQL asks
pingChecks the connection. Returns pongNothingNothing
get-mcp-session-idReturns the ID of this MCP sessionNothingNothing
get-context-helpExplains the rules for choosing the target project and connectionNothingNothing
list-projectsLists the projects that can be opened on this deviceNothingNothing
create-projectCreates a new local projectProjectA creation confirmation dialog
list-connectionsLists the connections and schemas allowed for AINothingNothing
list-tablesLists tables (search by name or description)NothingNothing
get-table-detailsColumns, indexes, foreign keys and constraints of tablesNothingNothing
erd-create-tablesDesigns new tables in an ERDERD (the DB is unchanged)Nothing
erd-modify-tablesModifies tables in an ERDERD (the DB is unchanged)Nothing
execute-queryRuns SQLDBA confirmation dialog, depending on the protection mode and policy
generate-codeGenerates source files with the project's template packsFiles in the project folderNothing

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.

ArgumentToolsContents
projectIdAll tools except list-projects, create-project and the ping groupThe target project, as returned by list-projects or create-project. If that project is not open, the desktop app opens it
connectionId, database, schemalist-tables, get-table-details, erd-create-tables, erd-modify-tables, execute-query, generate-codeThe 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 projectId argument, then --project-id in the client configuration, then the project open in the desktop app. If the configuration has --project-id and you pass a different projectId, 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-connections leaves 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

ArgumentContents
nameThe project name. Leading and trailing spaces are removed; up to 100 characters
dataSourceThe 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

ArgumentContents
searchText 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

ArgumentContents
tableNamesA 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

ArgumentContents
tableDefinitionsThe 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

ArgumentContents
alterationsThe list of tables to modify. For each table, give tableName and the operations below
OperationWhat it can do
newTableNameRename the table
remarksOperationChange the table description (optional)
primaryKeyOperationsAdd or remove PK columns (optional)
columnOperationsColumn ADD, DROP, MODIFY, RENAME
indexOperationsIndex ADD, DROP
foreignKeyOperationsForeign key ADD, DROP
constraintOperationsUNIQUE, CHECK and EXCLUSION constraint ADD, DROP

Running SQL

execute-query

ArgumentContents
sqlThe 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.

OrderConditionResult
1DDL from a user restricted by the DDL Restriction permission in an account projectRefused
2The 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
3The 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 offA 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
4OtherwiseRuns immediately

After a statement passes the checks, committing works as follows.

CaseResult
The Data changes option is onAuto-commits
The Data changes option is offReturns with the transaction left open. Commit or roll back in NeoSQL's MCP: SQL Editor tab
DDL is sent while a transaction is openDoes 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

ArgumentContents
tableNamesThe 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-project and, depending on the protection mode and policy, for execute-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-code can 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.
  • 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.