Getting started

Install and connect MCP

Once you install the NeoSQL MCP server (neosql-mcp) in an external AI client, a client such as Claude Code uses the connections of a project in the desktop app to read schemas, design ERDs and run SQL. The MCP server is a small program the client runs, and it passes each request to the desktop app on the same computer. Database credentials stay in the desktop app and are not put in the client's config. What MCP is and which safeguards apply to an external AI are explained in AI and MCP.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

What you need

  • The desktop app: The desktop app must be installed on the same computer (macOS or Windows) (Install and update). MCP is not available in the web app.
  • Node.js 20 or later: The client downloads and runs the MCP server with npx. The client must be able to find npx in the environment it runs in. NeoSQLEnterprise runs the MCP server included in the app, so it does not need Node.js. See Connecting from NeoSQLEnterprise below.
  • Connections for the external AI: In the project's AI Settings window, turn on Enabled for the connections (Project AI settings). Connections with this option off are not visible to the external AI.
  • Without signing in, only local projects are handled. To work with account projects, sign in to the desktop app.

Choosing how to install

MethodClientsChoose it when
The app's MCP Client Setup windowClaude Code, Codex, Gemini CLI, Cursor, VS CodeIn most cases. It registers directly in the client's config file, or puts a config file that fixes the target project in a working folder
Claude pluginClaude Code, Cowork in the Claude desktop appYou want to install and update it as a Claude plugin
Manual configurationAny client that can run a stdio MCP serverYou use a client that is not in the list, or you manage config files yourself

Registering from the app

  1. Open a project in the desktop app and click the AI Settings button at the top of the project screen.
  2. Turn on Enabled for the connections the external AI will use, pick Default for the connection used by requests that name no target, and click the Save button.
  3. When the window closes, click the AI Settings button again, then click the MCP Client Setup button below the table.
  4. In Setup scope, choose Global, choose your client, and click the Register Globally button.
  5. In the confirmation window, check the path of the file to change and the content to add, then click the button at the bottom. The button's name depends on whether the config file and a NeoSQL entry already exist.
  • Only the NeoSQL entry is added to the config file; other settings stay as they are.
  • How to use it from one working folder only or fix the target project, and where each client's config file goes, are explained in MCP client setup.

Installing the Claude plugin

In Claude Code and in Cowork in the Claude desktop app, you can install NeoSQL MCP as a plugin. The plugin runs a fixed version of neosql-mcp, and you get new versions by updating the plugin. Chat in Claude does not run the plugin's MCP server.

Adding it in the Claude app

  1. On claude.ai or in the Claude desktop app, open Customize › Plugins.
  2. Find NeoSQL MCP and click the Add button.
  3. If a dialog says the plugin includes a local MCP server, click the Continue button.
  4. To use it in Claude Code, restart Claude Code.
  • The plugin is saved to your claude.ai account. Claude Code (2.1.273 or later) signed in with the same account loads it the next time it starts.

Installing from the terminal

To use Claude Code without signing in to a claude.ai account, or to install with commands, add the plugin marketplace NeoSQL provides and install the plugin.

claude plugin marketplace add unvus/neosql-mcp
claude plugin install neosql-mcp@neosql
  • A plugin installed from the terminal does not update automatically by default. Update it with claude plugin update neosql-mcp@neosql, or turn on automatic updates for the neosql marketplace in the Marketplaces tab of Claude Code's /plugin screen.

Using the plugin together with other configs

  • If Claude Code has both a config (registered from the app or added manually) and the plugin, both MCP servers run and the NeoSQL tools appear twice. Check the running servers with /mcp in Claude Code and turn one off.
  • The plugin has no setting that fixes the target project. To fix a project for a working folder, put a config file made with the app's Working directory scope in that folder, and turn the plugin off by adding the entry below to that folder's .claude/settings.local.json. Write neosql-mcp@synced for a plugin added in the Claude app, or neosql-mcp@neosql for one installed from the terminal. If you installed it both ways, add both entries.
{
  "enabledPlugins": {
    "neosql-mcp@synced": false
  }
}

Configuring manually

Put the content below in the client's config file. It is the same as what the app's MCP Client Setup window builds. Where the config file goes is explained in MCP client setup.

Claude Code, Gemini CLI, Cursor:

{
  "mcpServers": {
    "neosql": {
      "command": "npx",
      "args": ["-y", "neosql-mcp"]
    }
  }
}

VS Code:

{
  "servers": {
    "neosql": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "neosql-mcp"]
    }
  }
}

Codex:

[mcp_servers.neosql]
command = "npx"
args = ["-y", "neosql-mcp"]
  • If the config file already has other MCP servers, add only the neosql entry.
  • A client that is not in the list can register it with the same command (npx) and arguments (-y neosql-mcp) if it can run a stdio MCP server.
  • To fix the target project, add --project-id=<project ID> at the end of the arguments. The project ID appears in the preview when you choose the Working directory scope in the app's MCP Client Setup window. With a fixed project, the external AI cannot target other projects, and the tool that creates a new project (create-project) is refused.

Connecting from NeoSQLEnterprise

NeoSQLEnterprise is the desktop app that connects to a NeoSQL server your company installs and runs. In NeoSQLEnterprise you register the MCP server the same way. The differences are below.

  • NeoSQLEnterprise includes the MCP server. The config that the app's MCP Client Setup window builds runs this MCP server with the NeoSQLEnterprise app's executable instead of npx. You need neither Node.js nor an internet connection, and the MCP server's version always matches the app.
  • The config holds the path of the app's executable, the path of the MCP server file inside the app, the ELECTRON_RUN_AS_NODE environment variable and the --profile=enterprise argument. ELECTRON_RUN_AS_NODE makes the executable run only the MCP server without opening the app window. --profile=enterprise makes the MCP server pass requests to the NeoSQLEnterprise app instead of the NeoSQL app.
  • For manual setup, copy the preview from the app's setup window and paste it. For an app installed in the macOS Applications folder it looks like this:
{
  "mcpServers": {
    "neosql": {
      "command": "/Applications/NeoSQLEnterprise.app/Contents/MacOS/NeoSQLEnterprise",
      "args": [
        "/Applications/NeoSQLEnterprise.app/Contents/Resources/neosql-mcp/neosql-mcp.cjs",
        "--profile=enterprise"
      ],
      "env": { "ELECTRON_RUN_AS_NODE": "1" }
    }
  }
}
  • If you move the app to another folder or reinstall it in another folder, the paths in the config no longer match and the MCP server does not start. Register again from the app. Updating the app does not change the paths.
  • The Claude plugin connects only to the NeoSQL app, not to the NeoSQLEnterprise app. In Claude Code, register from the app or set it up manually.
  • Both apps use the same neosql entry in the config file, so one client connects to only one of the two apps. Registering from one app replaces the entry the other app made.

Checking the connection

  1. Keep the desktop app running. If it is not running, the MCP server launches the app when the external AI calls a tool 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; the plugin appears as plugin:neosql-mcp:neosql).
  3. In the chat, ask something like "Show me my NeoSQL projects". If the external AI gets the project list with the list-projects tool, the connection reaches the desktop app.
  • AI and MCP: What MCP is and the safeguards that apply to an external AI.
  • MCP client setup: The app's setup window, setup scopes, and where each client's config file goes.
  • Project AI settings: The window that sets MCP use and the change policies per connection.
  • MCP tools: The tools an external AI can call and the values they take.
  • Troubleshooting: What to check when MCP does not connect.