MCP Server

Mantidb includes a Model Context Protocol (MCP) server. When it's on, AI clients on your Mac can list your connections, read table structures and run queries through Mantidb — using the connections, SSH tunnels and safe mode you already set up, without ever seeing your passwords.

Turn on the server

1. Open Mantidb ▸ Settings… (⌘,) and choose MCP.
2. Turn on Run the MCP server. It's off by default.
3. Optionally change the Port. The default is 47340; any port from 1024 to 65535 works.

Status shows whether the server is running.

Address and protocol

The server listens only on your own Mac (127.0.0.1), never on the network:

http://127.0.0.1:47340/mcp

It uses the Streamable HTTP transport and supports MCP protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.

Tokens

Every client needs a token. Create one for each tool you connect, so you can revoke them separately.

1. In Settings ▸ MCP, click New Token….
2. Enter a Name, for example Claude Code.
3. Choose the scopes:
   • Read: list connections and tables, run reads — always on.
   • Write: run writes after you approve each one here — optional.
4. Under Connections, choose All connections or Only these, and pick the connections the token may use.
5. Create the token and copy it.

Tokens look like mdb_<id>_<secret>. The token is shown only once — copy it before closing the sheet. Its secret is stored in the macOS Keychain.

To stop a client from connecting, click Revoke next to its token.

After 10 requests with an invalid token within 60 seconds, the server answers with HTTP 429 for 5 minutes.

Connect a client

After you create a token, Mantidb shows ready-to-paste snippets for common clients, with your port and token filled in.

Claude Code

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

Claude Desktop, Cursor and other stdio clients

Clients that start MCP servers as a command use the mantidb-mcp bridge. Add it to the client's MCP configuration:

{
  "mcpServers": {
    "mantidb": {
      "command": "/Applications/Mantidb.app/Contents/MacOS/mantidb-mcp",
      "env": {
        "MANTIDB_MCP_TOKEN": "<token>"
      }
    }
  }
}

Adjust the command path if Mantidb isn't installed in /Applications.

Tools

The server offers these tools to clients:

• connection can be the connection's name or its id.
• max_rows defaults to 200, up to 5,000.

Approving writes

Writes through MCP always need your approval in Mantidb, whatever the connection's safe mode:

1. Mantidb shows a dialog: "MCP client “<token>” wants to run N statement(s) on <connection>".
2. Click Allow to run it, or Cancel. If the safe mode requires Touch ID, you're asked for it too.
3. If you don't answer within 30 seconds, the request is declined.

When a request contains several statements, they run together in one transaction. On a Read only connection, writes are always rejected.

Audit log

Mantidb keeps an audit log of MCP requests. Settings ▸ MCP shows the latest 25 entries, each with the time, tool, connection, outcome (ok, denied, error or unauthorized), SQL and token name.

• Refresh updates the list.
• Show in Finder reveals the full log, ~/Library/Application Support/Mantidb/MCP/audit.jsonl. It rotates when it reaches 5 MB.

The mantidb-mcp bridge

mantidb-mcp is a small command-line program inside the app bundle (Mantidb.app/Contents/MacOS/mantidb-mcp). It connects stdio clients to the running server:

• It finds the server's address and port automatically.
• If Mantidb isn't running, it launches it in the background.
• Each request can take up to 600 seconds.

It's configured with environment variables:

The MCP server can't ask you to trust a new SSH host key. For a connection that uses an SSH tunnel, connect to it once from the Mantidb app first, so its host key is already trusted.