# AI Agents via MCP

> Schemity is a local database MCP server, so Claude Code, Cursor, or any MCP host can read your schema and stage diagram edits you review. No database credentials for the agent.

Source: https://schemity.com/doc/ai-assisted-design/

Schemity is a **database MCP server**. 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 the diagram you want the agent to see. The server only sees diagrams open in the Schemity window, not files on disk.
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 asks you to open the connection it needs. For Claude Code the snippet is a single command (the panel fills in the path to your binary):

  ```bash
  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 can an agent do in Schemity?

The server exposes 16 tools.

**Reads** - free, and they never change anything:

- `open_schemity` - start Schemity, or bring its window to the front.
- `list_diagrams`, `get_schema`, `get_context_views` - the open diagrams (the active tab is marked), their entities, fields, relationships, and [context views](https://schemity.com/doc/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](https://schemity.com/doc/context-map/) can reveal.
- `get_data_dictionary` - the documented schema, descriptions included.
- `lint` - the [schema lint](https://schemity.com/doc/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_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.

## How does an agent show me a proposed change?

With `show_preview`. The agent passes the diagram's unsaved edits (`pending`, which it uses after `propose_changes`), 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](https://schemity.com/doc/schema-lint/) and [impact](https://schemity.com/doc/impact-analysis/) 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.

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. 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](https://schemity.com/doc/export-sql-ddl/).