Concepts

AI and MCP

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 AssistantMCP
Who calls whomNeoSQL calls the AI provider's modelAn external AI client calls NeoSQL. NeoSQL does not call any model
Where you chatThe 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 costCalls use the API key you registered, and the cost is charged to that keyDecided by the external client
Available inWeb, desktopDesktop only
Without signing inWorks in local projects with a device keyWorks with local projects only
Who asks before runningThe 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 keyDevice key
Stored inYour account (the NeoSQL server), encryptedThis device, protected by the OS secure storage
Can be registered inWeb, desktop when signed inDesktop
Monthly budgetCan be setNone
Usage recorded inYour accountThis device

The keys you can pick in the chat depend on the environment and whether you are signed in, not on the project type.

EnvironmentKeys you can pick
WebAccount keys. Account keys that use an http address, localhost or a private IP address can be picked only on the desktop
Desktop, not signed inDevice keys
Desktop, signed inBoth 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

WhatWhen
Your question, the recent conversation and feature instructions NeoSQL addsEvery time you send a message
The connection, Database and Schema names of the selected contextEvery time you send a message
Table and view lists, and the columns, keys, indexes, relationships and constraints of tablesWhen the AI looks them up with its tools, without asking
The SQL you asked to tune and its estimated execution planWhen you ask for query tuning
The failed SQL, its SQLSTATE and the error messageWhen 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.ColumnAI AssistantMCP
1EnabledWhen off, the connection cannot be picked as contextWhen off, the connection is left out of the connection list and tool calls targeting it are rejected
2DefaultThe context selected first when a new chat startsThe target used when a tool call does not name one
3Schema changesWhen on, DDL the AI wrote runs without confirmation; when off, you confirm before it runsWhen on, DDL runs without confirmation; when off, NeoSQL shows a confirmation dialog
4Data changesWhen on, INSERT, UPDATE and DELETE the AI wrote run without confirmation; when off, you confirm before they runWhen on, changes are committed automatically. When off, the transaction is left open and you commit or roll back in the NeoSQL SQL editor tab
5Allow data transferWhen on, row queries run without askingNot used
6Always mask sensitive dataWhen on, sensitive data is masked regardless of role. Available in account projects onlySame 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 doesTools
Connection checks and helpping, get-mcp-session-id, get-context-help
Projectslist-projects, create-project
Reading schemaslist-connections, list-tables, get-table-details
ERD design (database unchanged)erd-create-tables, erd-modify-tables
Running SQLexecute-query
Code generationgenerate-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.
OrderConditionResult
1DDL from a user under DDL Restriction in an account projectRejected without running
2The 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
3The 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 offNeoSQL 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
4Anything elseRuns 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.