Walkthroughs

Design an ERD with an external AI (MCP)

You design a wishlist table for the demo shop by talking with an external AI client (for example, Claude Code) and apply it to the database. When you finish, a wishlist table that references customer and product exists in both the ERD and the database. The external AI calls NeoSQL as a tool to read the schema and edit the ERD, but you check the step that applies changes to the database on the NeoSQL screen. What MCP is and which safeguards apply is explained in AI and MCP.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

Before you start

  • You need the desktop app. The MCP server passes requests to the desktop app on the same device. Use MCP in the desktop app. Without signing in, only local projects can be used.
  • The device running the external AI client needs Node.js 20 or later, because the client starts the NeoSQL MCP server with npx.
  • Open a project that has the demo shop's shop-db connection. For ERD design alone, a connection without database connection details is enough. To apply to the database, it needs connection details.
  • Apply to a development database, not production. For a production database, first add the safeguards by following Connect to a production database safely.

Set the connection policy and register the client

Decide which connection the external AI uses and what it may change before registering the client, because once registered, the client can call tools right away.

  1. Click the AI Settings button at the top of the project screen. Turn on the Enabled option (1) for shop-db and select its Default option (2). Result: When the external AI calls a tool without naming a target, it uses the connection you chose as the default. Connections with the Enabled option off are invisible to the external AI.
  2. Leave the Schema changes option (3) off and click the Save button. Result: When the external AI tries to run DDL, a confirmation dialog appears in NeoSQL. The tools that edit the ERD do not change the database regardless of the Schema changes option.
  3. When the window closes, click the AI Settings button again, then click the MCP Client Setup button (7) below the table. Result: The MCP client setup window opens.
  1. Choose the Global item in the Setup scope field (1) and choose the client you use (4). Result: The preview shows what goes into the chosen client's global settings file. No account or database passwords are included.
  2. Click the Register Globally button (6), check the file path and content in the confirmation dialog, and click its button. Result: Only the NeoSQL entry is added to the settings file, and other settings stay as they are. Keeping the file only in a working folder is explained in MCP client setup.

Check the connection

  1. Restart the external AI client and check that neosql is connected in its list of MCP servers (/mcp in Claude Code). Result: The client has started the NeoSQL MCP server. You do not know yet whether it reaches the desktop app.
  2. In the chat, ask "Show me the tables in shop-db in NeoSQL". Result: The client calls the list-tables tool and receives table names such as customer, orders and product. The connection reaches the desktop app.
  • If the desktop app is not running, the MCP server starts it and waits until it is ready. If that fails, start the app yourself and ask again.
  • Where to look when it does not connect is in 'Things to keep in mind' on MCP client setup.

Create a table through conversation

  1. Describe the table you want in the chat. For example: "Design a wishlist table in shop-db that holds customers' wishlists. It should reference customer and product, prevent the same customer from adding the same product twice, and record when it was added." Result: The external AI first reads the keys and types of customer and product with get-table-details, and chooses columns and foreign keys to match.
  2. When the external AI calls the erd-create-tables tool, check the table definition it passes in the client's tool approval prompt and approve it. Result: An ERD tab whose name starts with MCP: opens in NeoSQL, showing wishlist as a new table with its name in green. The ERD holds only the tables that were created, so there are no relationship lines yet. The new table also appears in the explorer.
  3. To see the relationships too, right-click customer and product in the explorer and choose the Explorer context menuAdd to Current ERD menu. Result: The two tables are placed in the MCP: ERD and connected to wishlist by relationship lines.
  • The database has not changed so far. wishlist exists only in the ERD and the project's design, and is shown as a change not yet applied to the database (ERDs and the real database).
  • One MCP: ERD is created per MCP session and connection and schema. More tables created in the same conversation are added to the same ERD.
  • You can ask for several tables at once. Tables with names that already exist are skipped.

Review and fix

A person should read the external AI's design before it is applied. After it is applied, changes mean altering a table that holds data, which is harder.

  1. In NeoSQL's MCP: ERD, click the wishlist table to open the detail panel. Check the column types, nullability, primary key, foreign keys and unique index. Result: The panel's fields are explained in Table detail panel.
  2. If something needs fixing, ask in the chat. For example: "Add a note column as a 200-character string to wishlist, and rename created_at to added_at." Result: The external AI edits the same ERD with the erd-modify-tables tool. Changed columns are shown with change markers. The database is not changed at this point either.
  3. You can also make small fixes yourself in NeoSQL's detail panel and save. Result: The next time the external AI reads it with get-table-details, it sees the design you fixed.
  4. To check the reasoning behind the design against data, ask for a query. For example: "Using orders and order_item, count whether any customer ordered the same product more than once." Result: The external AI runs a SELECT with execute-query and receives the result. The SQL stays in NeoSQL's MCP: SQL editor tab, and up to 200 rows are returned.
  • Query results can pass through the external client to the model provider the client uses. Be careful when letting it query tables with personal information.

Apply to the database

There are two ways to apply. Applying from the NeoSQL screen lets you see and choose all the DDL that will run, so it is the recommended way.

  1. Click the Apply Changes to DB... button in the info panel of NeoSQL's MCP: ERD. Result: The tables in the ERD with changes not yet applied go into the list (3), and the DDL to run appears in the preview (4).
  2. Read the DDL to the end, click the Execute DDL button (6) and confirm. Result: wishlist is created in the database, NeoSQL reads it back from the database, and the change markers disappear. The dialog's options are explained in Apply changes to the database.
  3. Ask the external AI to "read the structure of the wishlist you just applied again and check that it matches the original request". Result: The external AI receives the structure read back from the database with get-table-details and compares it with the request.

The other way is for the external AI to send DDL directly with execute-query. Such a request goes through NeoSQL's execution confirmation check.

ConditionResult
A user with the DDL Restriction permission in an account projectRefused. Request approval from the NeoSQL screen (DDL approval)
The connection protection mode is Read-only (block non-SELECT)Refused
The protection mode is Confirm (DDL + risky DML), or the Schema changes option is offA confirmation dialog appears in NeoSQL, and it runs only if you click run. It does not run if there is no answer within 45 seconds
OtherwiseRuns right away
  • The confirmation dialog appears on the NeoSQL screen. When you leave execution to the external AI, keep the NeoSQL window where you can see it.
  • When refused, the external AI is told that nothing ran and not to retry, and a MCP execution request rejected notification also appears in NeoSQL.
  • This way does not go through NeoSQL's apply dialog. After applying, check whether change markers remain in the ERD.

What's next