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.
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 findnpxin 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
| Method | Clients | Choose it when |
|---|---|---|
| The app's MCP Client Setup window | Claude Code, Codex, Gemini CLI, Cursor, VS Code | In 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 plugin | Claude Code, Cowork in the Claude desktop app | You want to install and update it as a Claude plugin |
| Manual configuration | Any client that can run a stdio MCP server | You use a client that is not in the list, or you manage config files yourself |
Registering from the app
- Open a project in the desktop app and click the AI Settings button at the top of the project screen.
- 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.
- When the window closes, click the AI Settings button again, then click the MCP Client Setup button below the table.
- In Setup scope, choose Global, choose your client, and click the Register Globally button.
- 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
- On claude.ai or in the Claude desktop app, open Customize › Plugins.
- Find
NeoSQL MCPand click the Add button. - If a dialog says the plugin includes a local MCP server, click the Continue button.
- 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 theneosqlmarketplace in the Marketplaces tab of Claude Code's/pluginscreen.
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
/mcpin 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. Writeneosql-mcp@syncedfor a plugin added in the Claude app, orneosql-mcp@neosqlfor 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
neosqlentry. - 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_NODEenvironment variable and the--profile=enterpriseargument.ELECTRON_RUN_AS_NODEmakes the executable run only the MCP server without opening the app window.--profile=enterprisemakes 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
neosqlentry 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
- 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.
- Restart the external AI client and check that
neosqlis connected in the client's MCP server list (/mcpin Claude Code; the plugin appears asplugin:neosql-mcp:neosql). - In the chat, ask something like "Show me my NeoSQL projects". If the external AI gets the project list with the
list-projectstool, the connection reaches the desktop app.
- If it does not connect, see 'MCP does not connect' in Troubleshooting.
- What an external AI can do once connected is explained in MCP tools. To follow the whole flow from start to finish, read Design an ERD with an external AI (MCP).
Related pages
- 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.