There are two ways to use AI with NeoSQL: AI Assistant, where you talk to an AI inside the NeoSQL screen, and MCP (Model Context Protocol), where an external AI tool such as Claude Code calls NeoSQL as a tool. The calls go in opposite directions, so the keys used, where data goes and the safeguards all differ. What the two share is a single set of policies you set for each connection.
The calls go in opposite directions
AI Assistant
MCP
Who calls whom
NeoSQL calls the AI provider's model
An external AI client calls NeoSQL. NeoSQL does not call any model
Where you chat
The AI Assistant panel on the right of the project screen. Open it with the Project railAI Assistant button or Ctrl+I (Cmd+I on macOS)
The chat of the external AI client (Claude, Codex, Gemini, Cursor, VS Code and others)
Model and cost
Calls use the API key you registered, and the cost is charged to that key
Decided by the external client
Available in
Web, desktop
Desktop only
Without signing in
Works in local projects with a device key
Works with local projects only
Who asks before running
The NeoSQL screen (query approval, execution confirmation)
The external client's tool approval. NeoSQL itself asks only about SQL caught by the protection mode or policy, and about creating projects
There are two kinds of API keys
AI Assistant calls models with the API keys you register. Keys are registered in the My pageProviders & API Keys screen and come in two kinds depending on where they are stored. The supported AI providers are OpenAI, Anthropic, Google and Ollama.
Account key
Device key
Stored in
Your account (the NeoSQL server), encrypted
This device, protected by the OS secure storage
Can be registered in
Web, desktop when signed in
Desktop
Monthly budget
Can be set
None
Usage recorded in
Your account
This device
The keys you can pick in the chat depend on the environment and whether you are signed in, not on the project type.
Environment
Keys you can pick
Web
Account keys. Account keys that use an http address, localhost or a private IP address can be picked only on the desktop
Desktop, not signed in
Device keys
Desktop, signed in
Both account and device keys, the same in local and account projects
If you do not pick one, the key marked as the primary key is used; when both account and device keys have a default, the account key's primary key comes first.
Context is the allowlist for the request
Before sending a message you must pick at least one Database and Schema with the Select Database Schema button. What you pick is everything the AI can see in that request. The AI's tools do not touch connections you did not pick, and the scope does not grow during the conversation.
Connections whose Enabled option is off in the AI settings cannot be picked. Connections for design only, without database connection details, are not used by AI Assistant either.
What reaches the AI provider
What
When
Your question, the recent conversation and feature instructions NeoSQL adds
Every time you send a message
The connection, Database and Schema names of the selected context
Every time you send a message
Table and view lists, and the columns, keys, indexes, relationships and constraints of tables
When the AI looks them up with its tools, without asking
The SQL you asked to tune and its estimated execution plan
When you ask for query tuning
The failed SQL, its SQLSTATE and the error message
When you ask the AI about an SQL error
Values of actual rows (up to 10 rows at a time)
When the AI runs a query. On a connection with Allow data transfer turned off, the AI requested a database query. card appears on screen, and the query runs only after you approve
Allow data transfer is on for new connections, so at first row values are queried and sent without asking. Turn Allow data transfer off to be asked before row values are sent. Choosing Auto-approve subsequent queries on an approval card stops the questions for that conversation.
Query SQL cards in a response run automatically on this device against the database when the response ends, and show their results. Those results are not sent to the AI provider.
Requests are sent to the AI provider directly: from the local server on this device on the desktop, from the NeoSQL server on the web. If you use a model running on this device or in your company, such as with Ollama, requests go only to that address.
In account projects, columns marked as sensitive are masked according to the current user's role, and turning on Always mask
sensitive data for the connection masks them regardless of role. Local projects have no masking.
Chat history is stored in your account for account projects and on this device for local projects.
The connection policies both follow
Clicking the AI Settings button at the top of the project screen opens a table where you set policies for each connection. AI Assistant and MCP both follow this table, so a policy you turn on for AI Assistant also applies to external MCP clients.
No.
Column
AI Assistant
MCP
1
Enabled
When off, the connection cannot be picked as context
When off, the connection is left out of the connection list and tool calls targeting it are rejected
2
Default
The context selected first when a new chat starts
The target used when a tool call does not name one
3
Schema changes
When on, DDL the AI wrote runs without confirmation; when off, you confirm before it runs
When on, DDL runs without confirmation; when off, NeoSQL shows a confirmation dialog
4
Data changes
When on, INSERT, UPDATE and DELETE the AI wrote run without confirmation; when off, you confirm before they run
When on, changes are committed automatically. When off, the transaction is left open and you commit or roll back in the NeoSQL SQL editor tab
5
Allow data transfer
When on, row queries run without asking
Not used
6
Always mask
sensitive data
When on, sensitive data is masked regardless of role. Available in account projects only
Same as AI Assistant
Some rules come before this table. If the connection's protection mode is Read-only (block non-SELECT), AI Assistant runs nothing but SELECT; if it is Confirm (DDL + risky DML), it always confirms regardless of the policy. In account projects, users under DDL Restriction cannot run DDL through AI either.
Policies are set per connection. Public connections are changed by the project owner, private connections by the connection's owner, and local projects by the user of this device.
A connection with the Design only badge has no database connection details. External MCP clients cannot use execute-query on it, but can use the schema reading, ERD design and code generation tools. The execution policy columns do not apply.
AI Assistant can also create or change tables in an ERD through chat. These tools save to the ERD only and do not change the database.
Safeguards of MCP
Desktop only. The MCP server (neosql-mcp) is a program the external AI client runs on the same computer, and it passes requests to the desktop app through a channel inside this device. The actual work is done with the projects and connections the desktop app has. If the app is not running, the MCP server starts it and waits up to 40 seconds for it to be ready. Use MCP in the desktop app.
Without signing in, only local projects are available. Account projects require signing in to the desktop app.
The settings to add to an external client are produced with the MCP Client Setup button (7) in the AI Settings dialog. This button exists only on the desktop.
These are the tools MCP can call. The inputs and outputs of each tool are described in MCP tools.
What it does
Tools
Connection checks and help
ping, get-mcp-session-id, get-context-help
Projects
list-projects, create-project
Reading schemas
list-connections, list-tables, get-table-details
ERD design (database unchanged)
erd-create-tables, erd-modify-tables
Running SQL
execute-query
Code generation
generate-code
ERD tools do not change the database.erd-create-tables and erd-modify-tables only save virtual tables and changes to an ERD. The result appears in an ERD tab created for each MCP session and location (connection, Database and Schema). To apply it to the database, apply the changes in NeoSQL (ERDs and the real database), or have the external AI send the DDL with execute-query.
Every statement in execute-query goes through a confirmation check. The first matching row from the top applies, and if any one of several statements is rejected, none of them runs.
Order
Condition
Result
1
DDL from a user under DDL Restriction in an account project
Rejected without running
2
The connection's protection mode is Read-only (block non-SELECT) and the statement is not a query (INSERT, UPDATE, DELETE, DDL and so on)
Rejected without running
3
The protection mode is Confirm (DDL + risky DML) and the statement is DDL or an UPDATE·DELETE without a condition, or it is DDL and Schema changes is off
NeoSQL shows a confirmation dialog, and the statement runs only if the user chooses to run it. Without an answer within 45 seconds, it does not run
4
Anything else
Runs right away
When a statement is rejected, the external AI is told that nothing was run and that it should not retry, and rejections caused by a setting are also shown on the NeoSQL screen.
For INSERT, UPDATE and DELETE that pass the confirmation check, Data changes decides whether they are committed automatically, and the SQL stays in a NeoSQL SQL editor tab. Query results return up to 200 rows (or the plan's row limit if lower).
create-project shows a confirmation dialog in NeoSQL and creates the project only if the user agrees. generate-code saves files without asking and may overwrite existing files.
Returned data goes to the external client's model. Schemas and query results returned through MCP pass to the external AI client and may be sent to the model provider that client uses. NeoSQL cannot control what happens after that. In account projects, role-based masking and Always mask
sensitive data also apply to MCP results.
Approval is up to the external client. If the external client is set to approve tools automatically, calls arrive without any user confirmation. On the NeoSQL side, the defenses are the connection policies above and the execution confirmation check.
Things to keep in mind
Check SQL written by AI before running it. For connections to production databases, it is safer to leave Schema changes and Data changes off.
The NeoSQL desktop app must be running while you use MCP. If you close it, tool calls from the external client are not processed.
On the MCP path NeoSQL does not call any model, so nothing is recorded against NeoSQL AI usage or budgets.
Related pages
Providers & API Keys: the screen for registering account and device keys and viewing usage.
Project AI settings: the dialog where you set AI and MCP policies for each connection.
AI Assistant: the chat panel where you pick context, approve queries and run SQL cards.
Install and connect MCP: the ways to install NeoSQL MCP in an external AI client and to check the connection.
MCP client setup: the dialog for registering NeoSQL MCP in an external AI client.
MCP tools: the inputs and outputs of each MCP tool.