AI Agents via MCP

Schemity is a database MCP server (what it does and how it compares). Your AI agent - Claude Code, Claude Desktop, Cursor, Codex, OpenCode, or any other host that speaks the Model Context Protocol - connects to the Schemity app on your machine, reads the diagram you have open, draws proposed changes for you to look at, and stages edits you review before anything is saved. The agent never gets database credentials of its own, and nothing it does writes to a database: a migration only runs when you click Migrate.

Schemity used to ship a built-in AI chat with bring-your-own-key providers. The MCP server replaced it: your agent host already owns the model, the keys, and the conversation, so Schemity no longer duplicates them. On first launch after the update, the old provider keys are removed from your OS keychain.

The MCP server is a desktop feature. It is not available in the web version or on an expired trial; an active desktop license keeps it on.

How do I connect an agent?

1. Open Schemity. The agent reads and edits the diagrams open in its window; when the one you mean is not open, the agent can find and open it for you.
2. Open the MCP panel from the plug icon in the control bar, or with ⌘⇧A (macOS) / Ctrl+Shift+A (Windows/Linux). It shows the server status, its URL, the bearer token, a connection test, and a ready-to-paste setup snippet for each host.
3. Paste the snippet for your host.

Hosts connect in one of two ways, and the panel’s snippet for each host already picks the right one:

• stdio - Claude Code, Claude Desktop, Codex, and OpenCode start the Schemity binary with --mcp, a small MCP server that forwards to the app. Because the host starts it, it can also start Schemity when the app is closed: the agent calls open_schemity, the window comes to the front, and the agent finds and opens the diagram you need. For Claude Code the snippet is a single command (the panel fills in the path to your binary):

  claude mcp add --scope user schemity -- "/Applications/Schemity.app/Contents/MacOS/schemity" --mcp

  Codex takes the same command with codex mcp add, or a [mcp_servers.schemity] entry in ~/.codex/config.toml; OpenCode takes a local entry in opencode.json; Claude Desktop takes a command entry in claude_desktop_config.json - restart it after saving.

• Streamable HTTP - Cursor and any other HTTP client connect to http://127.0.0.1:7332/mcp with the bearer token in an Authorization header (Cursor reads both from ~/.cursor/mcp.json). The panel lets you change the port. An HTTP host cannot start the app, so keep Schemity open.

If you registered Claude Code with the older HTTP command, run claude mcp remove --scope user schemity first, or the add command reports that schemity already exists.

What do I ask the agent?

Ask in plain words; there is no command syntax. Your agent host gives the model every tool with its description, and the model calls Schemity’s when the request fits one. Saying “in Schemity”, “the diagram” or a diagram’s name makes that clear. In a code repository, “add a status column” alone may just as well send the agent to your model files.

• “Which diagrams do I have open in Schemity?”
• “Open my Coffee Shop diagram.”
• “Explain the schema in the current diagram. What are the main domains?”
• “What depends on the orders table?”
• “Arrange the current diagram: group the tables by domain, using this codebase to decide the groups.”
• “Untangle the relation lines in the Billing diagram.”
• “Show me the changes in the Coffee Shop diagram.”
• “What would my unsaved changes cost if I migrate?”
• “Check migrations/0042_add_status.sql against the shop database before I run it.”
• “Add a loyalty_points table to the diagram, linked to customers.”

In Claude Code, /mcp shows whether schemity is connected. If the agent answers from your files instead of the diagram, add “in Schemity” to the request.

Are there ready-made workflows?

Yes, since v2.14.5. Schemity offers three MCP prompts, step-by-step requests that call the right tools in the right order. Claude Code lists them as slash commands; other hosts show them wherever they list a server’s prompts.

Each one ends the same way as a plain request: the changes wait in History until you save them, and nothing touches the database.

Is there a skill that teaches my agent schema design?

Yes. designing-database-schemas is a free, open-source (MIT) agent skill that makes the agent decide what a schema would otherwise leave to the database’s defaults: a name on every constraint and index, an ON DELETE on every foreign key with its reason, money as numeric, the right identity for link and membership tables, and the locking cost of each migration statement on a table that already holds data. Its rules were measured on PostgreSQL, MySQL, SQL Server, SQLite and CockroachDB, and each links to the post with the measurements.

With Schemity connected, the skill’s last step stages the design on your diagram, runs lint and impact analysis, and has the agent fix each finding or say why it keeps it. Without Schemity, it still works and lists its assumptions instead.

In Claude Code:

/plugin marketplace add schemity/skills
/plugin install database-design@schemity

Other agents that read Agent Skills can copy the skill’s folder from the repository.

What can an agent do in Schemity?

The server exposes 18 tools.

Diagrams - which one the agent works on:

• open_schemity - start Schemity, or bring its window to the front.
• find_diagrams - search every saved diagram in every workspace, open or not, by a name hint.
• open_diagram - bring a diagram to the screen, opening it in a new tab when it is not open yet.

Reads - free, and they never change anything:

• list_diagrams, get_schema, get_context_views - the open diagrams (the active tab is marked), their entities, fields, relationships, and context views.
• get_dependencies - how contexts depend on each other through foreign keys, including indirect cycles spanning several contexts that no visual scan of the Context Map can reveal.
• get_data_dictionary - the documented schema, descriptions included.
• lint - the schema lint findings.
• get_pending_changes, analyze_impact, count_rows - what a connected diagram’s pending migration would do: data loss, statements that can fail on existing rows, table rewrites, dependent views and functions, and how far the change spreads. analyze_impact also reads the database again and says when it changed since the diagram loaded (a CI run or a teammate’s migration), since the migration is computed against the schema the diagram loaded; Refresh, then analyze again.
• analyze_migration_file - the same analysis for a migration file written by hand or generated by Prisma, Alembic, or Flyway, without executing any of it.
• check_relation_lines - which relation lines overlap or cross.
• show_preview - draw a change preview for you to look at: the diagram’s unsaved edits, a migration file, or a set of tables; see below.

Staged edits - they land in the open diagram as unsaved changes:

• propose_changes - create, change, and delete entities, fields, and relationships.
• group_entities - group entities into legends.
• route_relations - run relation lines around the tables so they cross less.

A plan that deletes something asks you first: a dialog names the agent and lists what it wants to delete, and Decline and roll back drops the whole plan, not only the deletions. The exception is the agent’s own work: it can delete an entity, field, or relationship it created since the last save without asking, as long as no one has edited it since.

On a new or empty diagram an agent names a single-column primary key id and a foreign key after the table it references, singular, plus _id (book_id). On a diagram that already has tables, it follows their naming instead.

How does an agent open another diagram?

Ask for it by name: “open my billing diagram”, or “work on the shop database instead”. The agent calls find_diagrams with your hint and shows you the closest matches, each with its workspace, database, and whether it is already open. You pick one, and open_diagram brings it to the screen.

The hint matches a diagram’s name and its database name alike, because you rarely know which of the two you remember, and each word can match either one: shop prod finds the diagram Shop on the database prod_main. A SQLite diagram matches on its file name, not the folders above it. The workspace name counts too, ranked after both. The diagram search in the Diagram Manager (⌘F / Ctrl+F) ranks the same way.

Opening a diagram never closes another one. If it is already open, the agent switches to its tab; otherwise it opens in a new tab and your other tabs, unsaved edits included, stay as they are. A diagram with a database is opened the way clicking it in the list opens it: the connection is tested first, so an unreachable database is reported instead of a half-loaded diagram. That test is where your computer may ask you something:

• macOS may ask for your login password so Schemity can read the connection’s password from the keychain. Click Always Allow to stop it asking again for that connection.
• A connection whose password comes from a command asks you to approve that command the first time it runs.

Both prompts are for you, not the agent. Schemity tells the agent to warn you before it opens a diagram with a database; the agent never sees what you type and waits up to two minutes while you answer. If you dismiss the keychain prompt, nothing opens and the agent asks whether to try again instead of retrying on its own. A diagram without a database opens straight away.

If Schemity is closed, an agent that started it over stdio calls open_schemity first, then finds and opens the diagram the same way. An HTTP host cannot start Schemity, so open the app yourself first.

How does an agent show me a proposed change?

With show_preview. The agent passes the diagram’s unsaved edits, a migration file’s SQL, or a list of tables, and Schemity opens a change preview: a throwaway, read-only canvas with just those tables and the neighbours a change reaches through a foreign key, laid out on its own. Unsaved edits are compared against the database, or on a diagram with no database, against the oldest state in History. A migration file is replayed against the connected database’s schema without executing any of it. Either way, the picture marks what the change does:

• a dropped table has a red border and a created one a green border;
• on a table that stays, dropped, added, and changed columns are tinted red, green, and blue;
• a renamed table carries its old name, and a rename written as RENAME is listed as a rename, not as a drop and an add;
• a relation that goes away or arrives with a table takes that table’s colour.

The Findings button opens the preview’s findings drawer. It starts with Planned changes, the migration in words, followed by the lint and impact findings for the shown tables. The preview’s title, Findings, and Close sit in the canvas’s top-right corner. Inside it, search covers only its tables and F10 still toggles the bars, while Save, History, and undo are blocked. Close or Escape leaves it, and nothing in it is ever saved or applied: the migration file stays the artifact, and you run it with your own tooling.

After propose_changes the agent does not open a preview. Its edits are already on your diagram, and an Agent changes button appears in the canvas’s top-right corner; click it to draw them on the change preview whenever you want to look. If the edits only move, color, or group tables, with no table, column, key, or index changed, the button tells you so instead, since everything is already on the canvas. The button goes away when you save or undo the edits.

When Schemity was already open and the agent ran an impact or lint check, it draws the result on its own. When it had to launch Schemity for your request, it answers in text and draws only if you ask to see it. Your own pending edits can be drawn the same way with Preview changes in the Impact drawer.

How do I review what the agent changed?

Agent edits go through the same undo history as your own. Open History (F6) to see every undo step and when it was made; a step made by an agent names the agent that made it. Undo anything you do not want, then save the diagram when you are happy with it. To see the edits as one picture instead of a list of steps, click Agent changes. On a connected diagram, press F7 to open the Impact drawer and see what the resulting migration would cost before you apply it, and Preview changes to see it drawn.

Nothing writes the diagram file until you save, and nothing touches the database until you run the migration yourself.

Where does my schema go?

The HTTP server listens on 127.0.0.1 only and rejects requests without the bearer token, and the stdio bridge talks to the app over a local socket. Schemity runs no model and no server of its own, so the schema goes exactly where your agent host sends it: to the model provider that host uses. If your host runs a local model - LM Studio, for example, is an MCP host for local models - the whole loop stays on your machine.

The token lives in your OS keychain, never in a plain file. Regenerate in the panel replaces it immediately, and any host still using the old token starts getting 401 errors until you paste the new one.

Troubleshooting

• “Schemity is not running” - only a stdio host can start the app; on an HTTP host such as Cursor, open Schemity yourself and retry.
• Port in use - pick a different port in the panel and click Restart.
• 401 Unauthorized - the token was regenerated since the host was configured; copy the current token into the host’s config.
• A tool says a diagram is “not open” - open that diagram in the Schemity window.

Next

Ship your design as SQL in Export SQL / Generate DDL.