Screens: AI, MCP and security

MCP client setup

The MCP Client Setup window builds what goes into the config file of an external AI client such as Claude Code so that it runs the NeoSQL MCP server (neosql-mcp), and can register it in that config file directly. What MCP is, what an external AI can do and which safeguards apply are explained in AI and MCP.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

What's on the screen

No.NameDescription
1Setup scopeWith the Global scope the client uses NeoSQL MCP from any folder, and the project to work on is chosen in NeoSQL each time. With the Working directory scope the client uses it only when run under that folder, and the target is fixed to the project this window was opened from. The Global scope is selected at first.
2Recommended locationWhere the config file for the chosen client and scope goes. See the table below.
3What it is forA short description of how the chosen scope behaves.
4ClientThe client to build the config for: Claude Code, Codex, Gemini, Cursor or VS Code. Claude Code is selected at first. When Claude Code is selected, the This is the setup for Claude Code (terminal). For Cowork in the Claude desktop app, install the Claude plugin. note appears below. In NeoSQLEnterprise, the This is the setup for Claude Code (terminal). The Claude plugin does not connect to NeoSQLEnterprise. note appears instead.
5Preview and the Copy buttonThe content to put in the config file and the file name. The button copies the content to the clipboard.
6Register Globally buttonRegisters NeoSQL MCP directly in the chosen client's global config file. Shown only with the Global scope.
7Download buttonSaves the preview content to a file. You choose where in the operating system's save dialog.
  • If no connection has the Enabled option turned on in the AI Settings window, the No Connection is enabled for MCP yet. First turn on ‘Enabled’ for a Connection in AI Settings. warning appears at the top. You can still build the config, but the external AI has no connection to use.
  • The config makes the client run npx -y neosql-mcp. The Working directory scope adds --project-id=<project ID>. No account or database password is included.
  • The config that NeoSQLEnterprise builds runs the MCP server inside the app with the NeoSQLEnterprise app's executable instead of npx, and adds the ELECTRON_RUN_AS_NODE environment variable and the --profile=enterprise argument. See Install and connect MCP for details.

The shape and location of the config file differ by client. ~ is your home folder.

ClientPreview file nameGlobal scope (global config file)Working directory scope
Claude Code.claude.json for the global scope, .mcp.json for the working folder scope~/.claude.json<working folder>/.mcp.json
Codexconfig.toml~/.codex/config.toml, or under CODEX_HOME if set<working folder>/.codex/config.toml
Gemini (Gemini CLI)settings.json~/.gemini/settings.json, or under GEMINI_CLI_HOME if set<working folder>/.gemini/settings.json
Cursormcp.json~/.cursor/mcp.json<working folder>/.cursor/mcp.json
VS Codemcp.json~/Library/Application Support/Code/User/mcp.json on macOS, %APPDATA%\Code\User\mcp.json on Windows<working folder>/.vscode/mcp.json

Opening the window

  1. Open a project in the desktop app. Without signing in, you can open only local projects.
  2. Click the AI Settings button at the top of the project screen. The window that sets the AI and MCP policy for each connection opens (Project AI settings).
  3. Turn on Enabled for the connections the external AI may use, choose Default for the connection used by calls that name no target, and click the Save button.
  4. When the window closes, click the AI Settings button again, then click the MCP Client Setup button below the table.

Registering globally

This is the simplest way to use NeoSQL MCP from any folder you work in.

  1. In Setup scope, choose Global, then choose your client.

  2. Click the Register Globally button. NeoSQL reads that client's global config file and shows a confirmation.

  3. Check the path of the file to change and the content to add, then click the button. The button depends on the situation.

    SituationButtonWhat it does
    The config file exists without a NeoSQL entryRegisterAdds only the NeoSQL entry and keeps the other settings
    The config file already has a NeoSQL entryReplaceReplaces only the NeoSQL entry with the new content
    There is no config fileCreateCreates a new config file
  4. When the NeoSQL MCP has been registered. notification appears, you are done. If the client is already running, restart it.

  • If the config file cannot be parsed (broken JSON or TOML) or you lack permission to read or write it, the file is left unchanged and an error is shown.
  • The file is written to a temporary file and then swapped in, so the original survives a failure while writing. If restoring the original also fails, a backup file <config file>.neosql-mcp.backup is left in the same folder and its path is shown.

Putting a config file in a working folder

To use NeoSQL MCP only in one repository, or to always target this project from that repository, put a config file in the working folder.

  1. In Setup scope, choose Working directory, then choose the client.
  2. Click the Download button and, in the save dialog, choose the place shown in Recommended location under your working folder. The file name is prefilled with the preview's name. If a file with the same name exists, the operating system asks whether to overwrite it.
  3. If a config file already exists, do not download; copy with the Copy button and paste into that file's neosql entry.
  • A config with the Working directory scope contains this project's ID. A client started with it cannot target other projects, and the tool that creates a new project (create-project) is rejected.
  • If the target project is not open in NeoSQL, NeoSQL moves to that project when a tool is called. If the current screen has unsaved changes, it does not move and the tool call fails.
  • On macOS, saving a file whose name starts with a dot (.mcp.json) may make the operating system ask about hidden files.

Checking the connection

  1. Keep the NeoSQL desktop app running. If it is not running, the MCP server launches the app and waits up to 40 seconds for it to be ready.
  2. Restart the external AI client and check that neosql is connected in the client's MCP server list (/mcp in Claude Code).
  3. In the chat, ask something like "Show me my NeoSQL projects". If the client calls the list-projects tool and gets NeoSQL's project list, the connection reaches the desktop app.
  • The ping tool checks only the client and the MCP server; it does not ask the desktop app. Check the connection to the app with list-projects or list-connections.
  • What an external AI can do once connected (read schemas, design ERDs, run SQL, generate code) and the values each tool takes are explained in MCP tools.
  • Depending on the connection's protection mode and policy, SQL sent by an external AI brings up a confirmation window in NeoSQL (the Confirm MCP DDL Execution window for schema changes, the Confirm MCP SQL Execution window for data changes), and creating a new project brings up the Confirm MCP Project Creation window. All three appear on the NeoSQL screen, so work where you can see the app. The policy and when these windows appear are explained in AI and MCP.

Things to keep in mind

  • Desktop app only. The MCP server passes requests to the desktop app on the same computer. The web app has no MCP Client Setup button. Account projects, too, must be open in the desktop app to be handled over MCP.
  • Without signing in, only local projects are handled. Targeting an account project fails with a message asking you to sign in to the desktop app.
  • The computer that runs the client needs Node.js 20 or later, and the client must be able to run npx.
  • Claude Code in this window is the setup for Claude Code run from a terminal. For Cowork in the Claude desktop app, install the Claude plugin (Install and connect MCP). NeoSQLEnterprise registers from this setup window instead of the Claude plugin.
  • If the external client is set to approve tools automatically, it runs SQL without asking. For connections to databases that must not change, turn off Enabled or connect with a database account that has no write permission.
  • Schemas and query results returned to the external AI may go to the model provider that client uses. NeoSQL cannot control what happens after that.
  • Install and connect MCP: Installing with the Claude plugin or manual configuration instead of this window.
  • AI and MCP: The difference between AI Assistant and MCP, the connection policy, and MCP's safeguards.
  • Project AI settings: The window that sets MCP use and the schema and data change policies per connection.
  • MCP tools: The tools an external AI can call and the values they take.
  • Design an ERD with an external AI (MCP): After connecting, design an ERD with an external AI and apply it to the database.