MCP server.

Let Claude Code, Cursor, Codex or Claude Desktop use your databases through Plasma, with per-connection access levels, masked results, read-only queries, and changes that only run after you approve them in Plasma.

What it is#

MCP (the Model Context Protocol) is how AI coding tools call external tools. Plasma can act as an MCP server so a tool such as Claude Code can look at the structure of a database, run read-only queries and propose changes, without ever receiving a password or a host name. Everything goes through Plasma, so Plasma’s own rules apply.

It is off by default, and every connection starts with no access.
Tools read in a read-only session, with sensitive values masked.
A tool can only change data when you approve the exact statement in Plasma.
Tools never get a password, host, user or file path.

Turn it on#

01
Enable the server
Settings → MCP server → Turn on the MCP server. A status line shows whether it is listening, or why it is not (for example when the port is in use).
02
Check the port
The default port is 47321. You can pick any port from 1024 to 65535; the server listens on 127.0.0.1 only.
03
Copy the setup for your client
Choose Claude Code, Cursor, Codex or Claude Desktop. Settings shows the exact snippet with your port and a hidden token; Copy copies it with the real token.
04
Give a connection access
In What AI tools may do, choose an access level for each saved connection. Nothing is visible to a tool until you do.

Client setup#

These are the forms Settings generates. <token> stands for the token shown (and copied) there; the port is the one you set.

Claude Code#

Run this once in a terminal.

Terminal

claude mcp add --transport http plasma http://127.0.0.1:47321/mcp --header "Authorization: Bearer <token>"

Cursor#

Add it to ~/.cursor/mcp.json.

~/.cursor/mcp.json

{
  "mcpServers": {
    "plasma": {
      "url": "http://127.0.0.1:47321/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Codex#

Add it to ~/.codex/config.toml.

~/.codex/config.toml

[mcp_servers.plasma]
url = "http://127.0.0.1:47321/mcp"
http_headers = { "Authorization" = "Bearer <token>" }

Claude Desktop and other stdio clients#

Clients that only speak stdio use a bridge that Plasma ships: plasma mcp. It reads the port and the token from Plasma’s own folder, so no token goes into the config file. Add the snippet to the client’s MCP config file. If you have installed the command-line tool, Settings shows the short form (command is the installed plasma and args is ["mcp"]); otherwise it shows the app binary with --plasma-mcp-bridge.

MCP config (with the command-line tool installed)

{
  "mcpServers": {
    "plasma": {
      "command": "/path/to/plasma",
      "args": [
        "mcp"
      ]
    }
  }
}

If Plasma is not running or the server is off, the bridge answers Open Plasma and turn on the MCP server in Settings.

Per-connection access#

Level	The tool may
Off	Nothing. The connection is not listed.
Structure only	List the connection and read its structure and notes.
Structure and read queries	Also run read-only queries.
Read, and propose changes	Also propose one statement at a time for you to approve.

A connection saved as Read-only cannot be set higher than read queries; the propose option is disabled and marked.
For a production connection with read or propose access, Settings warns that AI tools will read live data (and can propose changes to it).
Send unmasked values to MCP clients (shown for read and propose levels) turns masking off for that connection. Leave it off unless you need real values.
You can also reach the setting from the Connections home: Allow AI tools… on a saved connection.

The seven tools#

Tool	Needs	What it does
`list_connections`	Any access	The connections you allowed: id, name, engine, access level, read-only, production and whether it is open in Plasma. Never a host, user or path.
`get_schema`	Structure	Tables, columns, types, primary and foreign keys; pass a schema and table to narrow it, which also adds indexes. SQL engines.
`run_query`	Read queries	One read-only statement (SELECT, WITH, EXPLAIN, SHOW, VALUES, TABLE) in a read-only session. Up to `max_rows` rows (default 200, at most 1,000), a truncated flag, a 30-second limit, sensitive columns masked. PostgreSQL, MySQL/MariaDB, SQLite and ClickHouse.
`propose_change`	Propose	One INSERT, UPDATE, DELETE or DDL statement with a one-sentence summary. Nothing runs until you approve it in Plasma. Only works on the connection currently open in Plasma.
`check_proposal`	Any	Reports what became of a proposal: `waiting_for_approval`, `applied`, `declined`, `failed` or `expired`. Waits up to 45 seconds for you.
`get_memory`	Structure	Your database memory notes for the connection, so the tool reads your business rules before it writes SQL.
`remember`	Read queries	Proposes a note (up to 500 characters). You review and may edit it in Plasma before it is saved.

Approvals and check_proposal#

When a tool calls propose_change (or remember), Plasma brings its window forward and shows a card in the Assistant panel, in a thread labelled with the client’s name. It is the same card as the in-app agent’s: you read the statement and summary, then approve or reject. On PostgreSQL, approving previews the change with Safe Run first. The change goes through all the usual gates: read-only, Prod confirmation and Safe mode.

propose_change waits up to 45 seconds for your answer and then replies waiting_for_approval. The tool is told to keep calling check_proposal with the id until the answer is no longer waiting, and never to propose the same change twice.
An undecided proposal is withdrawn after 10 minutes (status expired). Plasma keeps at most 5 proposals waiting at once. A settled proposal’s outcome stays available for an hour.
A change can only target the connection that is open in Plasma right now, and it must be a SQL connection. If it is not open, the tool is told to ask you to open it.

Limits#

Up to 4 calls are handled at once; a request body is capped at 1,000,000 bytes.
Queries run on a separate read-only connection, not on your editor’s session.
Structure is cached for 60 seconds. Error messages have the host, user, password and database path scrubbed out.
Redis and OpenSearch connections can be listed and carry notes, but their data is not queryable through MCP yet; DuckDB connections expose their structure but are not queryable through run_query either.

Masking#

Results from run_query are masked always, whether or not presentation mode is on. Plasma masks emails, phone numbers, card numbers, IP addresses and columns whose names look sensitive, using the connection’s own column rules and your Masking style; passwords and secrets are fully masked. The one exception is the connection’s Send unmasked values to MCP clients switch.

Security model#

Loopback only. The server binds to 127.0.0.1 and answers only POST /mcp. The Host header must be 127.0.0.1:<port> or localhost:<port>, which blocks DNS-rebinding.
No browsers. Any request that carries an Origin header is rejected with 403. Browsers always send one on cross-site requests; local MCP clients do not.
Bearer token. Every request needs Authorization: Bearer <token>, compared in constant time before the body is read. The token is a random 256-bit value, shown masked in Settings with Show, Copy and Regenerate; regenerating takes effect at once and stops clients that hold the old one. It is stored in a file in Plasma’s folder that only your user can read (mode 0600 where the system has file modes) so the stdio bridge can read it.
Least data. Tools see only the connections you allowed, and results are masked, capped and scrubbed as above.
No silent writes. There is no tool that writes without an approval card.

Activity log and audit#

The bottom of the MCP section lists the last 50 calls: time, client, tool, connection and outcome (Done, Failed, Declined or Refused).

Every tool call is also written to the tamper-evident audit log, on every connection, with the source MCP tool. An entry holds the client and tool name, the SQL (cut at 2,000 characters), the outcome, row count and duration; the database user is never recorded for MCP calls.