Last updated: 2026-11-11

AI Integrations & MCP

Jam SQL Studio is designed as an AI-native SQL IDE. There are three ways to leverage AI with your databases: the built-in AI Chat Sidebar for conversational assistance right in the editor, the AI Workspace for file-backed collaboration with AI agents, and the Jam SQL Skill & MCP Server for external AI tools to safely interact with your databases.

Try it yourself Jam SQL Studio is free for personal use — the AI Chat Sidebar, AI Workspace, and local MCP server are all built in, on Mac, Windows, and Linux.
Download free

Install to first safe query in four steps

If you have not used the MCP server before, this is the whole path. The MCP endpoint itself is local — the server listens on 127.0.0.1, it is not routable from your network, and your saved connection credentials stay inside the app; the agent never receives a password or a connection string. Two things do travel, and it is worth being clear about both: the SQL runs against your database, so if that database is remote the traffic goes to it exactly as it would from the query editor; and whatever the agent sees — the SQL it writes, the rows a tool returns — goes wherever your AI client sends its context. A local model keeps it on the machine; a cloud client sends it to that provider like any other prompt and tool result. The detailed reference for each piece follows further down.

  1. Install Jam SQL Studio. Download the Mac, Windows or Linux build and open it. Free for personal use, no account.
  2. Connect a database. Click New Connection, pick the engine, fill in server, credentials and (optionally) a database, and click Connect. The MCP server exposes the connections you have saved here — see Connections. Nothing is exposed until the next step.
  3. Enable the MCP server and register it with your agent. In Settings → AI Integrations, turn Enable MCP server on (it is off by default), then copy the endpoint — http://127.0.0.1:14507/mcp unless the port was taken — and the bearer token. For Claude Code:
    claude mcp add --transport http jam-sql http://127.0.0.1:14507/mcp \
      --header "Authorization: Bearer YOUR_TOKEN_HERE" \
      --scope user
    For Codex CLI, add to ~/.codex/config.toml and export the token in your shell profile:
    [mcp_servers.jam-sql]
    url = "http://127.0.0.1:14507/mcp"
    bearer_token_env_var = "JAM_SQL_MCP_TOKEN"
    Other clients, and the jam-sql add-skill shortcut, are covered in Quick Start and Manual MCP Setup.
  4. Allow the first safe query. The permission level starts at Block, so an agent that has just connected can read schema and write into a query tab but cannot execute anything. Set it to Read-only in Settings → AI Integrations and the agent may run reads: SELECT, EXPLAIN, SHOW, PRAGMA and SQL Server system procedures that only read, such as sp_help — nothing that writes (see what Read-only runs). Then ask your agent something concrete, for example “list the tables in the Sales database and show me 10 rows from the largest one”. Writes stay unavailable until you move the level to Confirm, which asks you in the app for each one.
What the defaults already protect. Out of the box a query returns at most 1,000 rows and is cancelled after 30 seconds; tool calls are audited as metadata with the SQL text left out; and sharing your results grid or editor contents with an agent, letting it add new connections, and letting it write MetaInfo declarations are all off until you turn them on. An agent that wants to connect to one of your saved connections asks you first. See Permission Levels and Agent Capabilities for the full list.

Quick Start: Connect Your AI Tool

The fastest way to give your AI coding agent access to Jam SQL Studio is with the jam-sql skill. Run a single command — it auto-detects your agents (Claude Code, Cursor, Copilot, Codex, Windsurf, and 20+ more):

jam-sql add-skill

The jam-sql CLI is bundled with the app and installed to your PATH automatically. The skill teaches your AI agent what Jam SQL Studio can do and how to use it. For full MCP connectivity (query execution, schema access), also enable the MCP server in Settings → AI Integrations.

The same skill is in the public jamsql/skills repository, so npx skills add jamsql/skills --skill jam-sql installs it as well. In Claude Code you can also install it as the Jam SQL Studio plugin.

Which AI tools work with Jam SQL Studio?

The MCP server speaks the standard Model Context Protocol over a local HTTP endpoint, and jam-sql add-skill auto-installs the skill for the agents below. Any MCP-compatible client can connect using the endpoint and token from Settings → AI Integrations; clients that only start local stdio servers use npx -y @jamsql/mcp.

AI toolHow it connectsSetup
Claude CodeSkill + MCPjam-sql add-skill (auto-detected), or the Jam SQL Studio plugin
Claude DesktopMCP over stdio via @jamsql/mcpnpx -y @jamsql/mcp in claude_desktop_config.json (setup)
CursorMCP (.cursor/mcp.json)Config auto-generated in the AI Workspace
GitHub CopilotMCP (.vscode/mcp.json)Config auto-generated; uses VS Code MCP support
Codex CLI (OpenAI)Skill + MCPjam-sql add-skill (auto-detected)
OpenCodeMCP (opencode.json)Config auto-generated in the AI Workspace
Windsurf, Cline, WarpSkilljam-sql add-skill (auto-detected)
Any other MCP clientHTTP MCP endpoint + token, or stdio via @jamsql/mcpPoint the client at the endpoint, or run npx -y @jamsql/mcp (works with LangChain, custom agents, and other MCP-capable tools)

Claude Code plugin

The Jam SQL Studio plugin for Claude Code is the same jam-sql skill, packaged as a plugin. It lives in the public jamsql/skills repository, which is also a Claude Code plugin marketplace. In Claude Code, run:

/plugin marketplace add jamsql/skills
/plugin install jam-sql@jamsql
  • Claude works through the jam-sql CLI that the app installs, so Jam SQL Studio must be running with Settings → AI Integrations → Enable MCP server on. On first use Claude runs jam-sql pair, and you approve the dialog in the app (see Pairing).
  • Queries follow each connection's permission level, and at Confirm each write waits for your approval in Jam SQL Studio.
  • The plugin has no MCP server of its own. To give Claude Code the MCP tools as well, add the server as described under Manual MCP Setup.

AI Chat Sidebar

The AI Chat Sidebar brings conversational AI directly into the Query Editor and SQL Notebooks. Click the AI button in the toolbar to open a chat panel alongside your work.

No extra subscription required. The AI Chat Sidebar uses your locally installed AI CLI. Jam SQL Studio reuses your existing CLI setup — it does not proxy, bill, or require any additional AI subscription or API key configuration.

Supported AI Backends

The AI Chat Sidebar supports two AI backends. Install either or both — Jam SQL auto-detects available CLIs:

  • Claude CLI (Claude Code) — Anthropic's AI coding assistant
  • Codex CLI — OpenAI's command-line coding agent

When both CLIs are installed, a segmented control in the sidebar header lets you switch between them. Your preference is saved and applied to new tabs automatically.

How It Works

  1. Install Claude CLI or Codex CLI (or both)
  2. Open a Query Editor or SQL Notebook
  3. Click the AI button in the toolbar to open the chat sidebar
  4. Ask your AI about your SQL — it can read your editor content, run queries, and update your code

Features

  • Database-aware — the AI auto-connects to the MCP server for schema introspection and query execution
  • Editor integration — the AI can update your SQL directly in the editor
  • Notebook support — In SQL Notebooks, the AI understands your cell structure and can add, edit, and execute cells on your behalf
  • @-mentions — type @ to reference database objects from the Object Explorer
  • Streaming responses — see answers appear in real-time with inline tool call indicators; a summary of the model's thinking appears in a collapsible block above the answer
  • Session continuity — conversations persist across tab switches and session restores
  • Multi-backend — switch between Claude and Codex with a single click; each manages its own authentication
  • Zero configuration — if a supported CLI is installed, the sidebar auto-connects to the MCP server. No API keys to paste into Jam SQL.
  • Privacy — all communication happens locally between the app and the CLI binary on your machine

AI Task Launchers

Six one-click buttons, placed where the task is relevant, open the AI Chat Sidebar with a ready-made prompt for a common job — no need to type it yourself. Every launcher tells the agent not to execute anything itself; it writes SQL into your editor (or answers in chat) for you to review and run.

  • Explain this table / Generate test data — Object Explorer, right-click a table or view
  • Document this schema — Schema Overview toolbar
  • Optimize this query / Explain this error — Query Editor (Optimize is on the toolbar, next to Format; Explain this error appears alongside a failed statement)
  • Diagnose server load — Performance Dashboard toolbar; asks the agent to check top CPU queries, wait stats, and long-running sessions (read-only) and say which query to fix first

Neither compare surface carries an AI launcher. Schema Compare and Data Compare both produce their migration SQL through Generate Script in the compare tab, which works from the real diff rather than from a summary of it.

A connected agent can still read the schema comparison you have open: each Schema Compare tab's current result is listed on the MCP compare-snapshot resource (sql-studio://compare/schema, marked initiatedBy: "user"), and the agent can fetch the full differences or generate the sync script from it — your actual diff, with the options and filters you chose, no re-run needed. The entry follows the tab: it updates when you re-compare or change options, and disappears when you close the tab.


Understanding the Three Approaches

Jam SQL Studio offers flexibility in how you work with AI. Depending on your workflow, you might prefer one approach or combine them:

AI Chat Sidebar vs AI Workspace vs Skill / MCP Server

AspectAI Chat SidebarAI WorkspaceSkill / MCP Server
Where it runsRight panel in Query Editor / SQL NotebookInside Jam SQL Studio (integrated terminal)External AI tools (Claude Code, Cursor, Copilot, Codex, etc.)
Best forQuick questions, SQL help, interactive editingFile-backed iteration with AI agentsComplex analysis, multi-step tasks from external tools
Context sharingAutomatic: editor content, connection, database objectsFile-backed: .sql files, CLAUDE.md, schema exportsSkill: procedural knowledge; MCP: live snapshots of tabs, editors, results
ConfigurationInstall Claude CLI or Codex CLIEnable AI Workspace in Settingsjam-sql add-skill + enable MCP Server

AI Workspace (Inside the App)

The AI Workspace provides file-backed query tabs that sync bidirectionally with .sql files. Combined with the integrated terminal, this enables AI agents (like Claude Code) to edit your queries in real-time.

Pro Feature: AI Workspace sync features (file sync, schema export, context files) require Pro. The AI Terminal itself is free for all users.

AI Workspace Features

  • Bidirectional file sync — Query tabs sync to .sql files; AI edits the file, your tab updates automatically
  • Auto-generated context — CLAUDE.md and AGENTS.md contain connection info, schema summary, and recent execution results
  • Schema export — Detailed table/view/procedure definitions exported to .schema/ for granular @table mentions
  • Results history — Query results saved to .history/ so AI agents can analyze output and iterate
  • Knowledge pack — App capabilities and how-to documentation in .knowledge/
  • MCP environment variables — Terminal sessions include JAM_SQL_MCP_ENDPOINT and JAM_SQL_MCP_TOKEN for direct MCP access
  • Auto-generated MCP configs — Config files for popular AI tools (.mcp.json, .cursor/mcp.json, opencode.json, .vscode/mcp.json) are automatically created with endpoint and token
  • Codex MCP shim — Codex CLI has no project-level MCP config file to auto-generate the way Claude Code, Cursor, and OpenCode do, so when Codex is detected, Jam SQL Studio writes a small codex wrapper ahead of the real binary on the terminal's PATH. Running plain codex in the AI terminal transparently wires it to the local MCP server — no --config flags or ~/.codex/config.toml edits needed. When MCP is off, the wrapper is a plain pass-through to the real Codex binary.

Zero-Config AI Tool Setup

When you open an AI Workspace terminal, MCP configuration files are automatically generated in the workspace directory, and Codex additionally gets a PATH-level shim (see above). AI agents like Claude Code, Cursor, OpenCode, and Codex will automatically connect to the MCP server without manual configuration. These files are added to .gitignore to prevent accidental token commits.

How to Use AI Workspace

  1. Open Jam SQL Studio and go to Settings → AI & Terminal
  2. Enable AI Workspace and select or create a workspace folder
  3. Open the integrated terminal (View → Terminal or click Terminal in the sidebar)
  4. Run your AI coding agent (e.g., claude for Claude Code)
  5. The agent can read/edit .sql files, and your query tabs update in real-time
The AI Workspace settings panel showing workspace folder configuration and sync options.
The AI Workspace settings panel showing workspace folder configuration and sync options.

Setup Confirmation

Before Jam SQL Studio sets up an AI workspace for a connection, it asks for confirmation. The dialog lets you pick the target database and explains exactly what's about to happen: it exports schema DDL — tables, views, procedures, functions — no table data is read or exported, and nothing is executed against your database. Choose Set up workspace to proceed, or Cancel to back out with nothing created.

Tick Don't ask me again to skip this dialog on future clicks. You can turn it back on any time from Settings → AI & Terminal → Confirm before setting up a workspace.

While the workspace is being set up, the setup overlay shows progress with a Cancel export button. Cancelling stops the export right away — the terminal stays open and usable, it just won't have the exported schema files. The X in the corner only dismisses the overlay to the background; the export keeps running until it finishes or you cancel it.

Persistent Workspaces (Pro/Trial, opt-in)

By default, an AI workspace folder is temporary: it's deleted when you close its terminal (or on the next app start if it wasn't). Turn on Keep this workspace in an AI terminal's context bar — also listed in Settings → AI & Terminal → Persistent workspaces — to make one connection's workspace folder survive: it's reused instead of recreated, so your .history/ and any notes the agent left behind carry over across sessions and app restarts. This is off by default and set per connection — keeping one connection's workspace has no effect on any other.

Turning it back off ("Stop keeping") only removes the connection from that list — it does not delete the folder or anything inside it. The folder and its files stay on disk exactly as they were; a session already running in it keeps working normally. An un-kept folder is only cleaned up the way any ordinary AI workspace folder is: the next time you start the app. To find a workspace's folder with your file manager, expand that terminal's context bar and click Open workspace folder.

Pro Tip: Use @ Mentions

With schema export enabled, you can use @Customers or @Orders in your prompts to reference specific table definitions from the .schema/ folder.

Your First Five Minutes in the AI Terminal

Open the integrated terminal and Jam SQL Studio prints a welcome banner. If it detects Claude Code or Codex CLI already installed, the banner names them and tells you the command to run; if neither is installed, it shows both install commands side by side. Claude Code and Codex are treated as equals everywhere in Jam SQL Studio — neither is the default, neither is an afterthought.

  1. Install an agent, if you don't have one yet. Run either (or both) — Jam SQL Studio auto-detects whichever CLIs are on your machine:
    npm i -g @anthropic-ai/claude-code   # Claude Code
    npm i -g @openai/codex               # Codex CLI
  2. Start it. Once an agent is detected, a Start button for it appears in the terminal's context bar — Start Claude Code and Start Codex sit side by side, for whichever agents are actually installed. Click one, or just type claude or codex yourself. If you'd rather skip the click, turn on Auto-launch agent on open in Settings → AI & Terminal (off by default) — a freshly opened AI terminal then writes the launch command in for you instead of leaving a blank prompt. Choose a specific agent there, or leave it on “Auto” to prefer Claude Code when both are installed.

If a detected agent is missing the jam-sql skill, a dismissible row in the terminal points it out with the exact command to fix it (jam-sql add-skill).

Five things to try:

  • Write a query from the schema — “Look at the schema and write a query that finds our top 10 customers by revenue.”
  • Explain a procedure — “Explain what the usp_ProcessRefund procedure does.”
  • Optimize the active tab — “This query in my active tab is slow — can you make it faster?”
  • Explain an error — “My last query failed — what does this error mean and how do I fix it?”
  • Draft a migration — “Draft a migration that adds a refunded_at column to orders.”

The security model: your agent never sees your database password — Jam SQL Studio owns every connection. In the terminal, the agent only ever touches .sql files, which sync to your query tabs for you to review. Nothing runs against your database until you do: read the agent's SQL in the tab and click Execute (or press F5 or Cmd/Ctrl+Enter) yourself.

Or let the agent ask you to run it (Pro/Trial): instead of writing SQL and waiting for you to notice, the agent can ask Jam SQL Studio to run one of your query tabs directly. You always see a confirmation toast with the whole SQL (in a scrollable box) and the agent's stated reason before anything runs, with three choices — Run (this one time), Always this session (stop asking again for that connection and database, for the rest of this terminal session), or Deny. Closing the prompt without choosing counts as Deny, so the agent is never left waiting forever on an answer that never comes.

Want the agent to query the database directly instead of just drafting SQL for you to run? Click MCP: off · Enable read-only in the context bar (or enable MCP from Settings → AI Integrations). This turns on the local MCP server in read-only mode — the agent can run SELECT-class queries and see the results itself, without ever gaining write access unless you widen the permission level yourself afterward. See MCP Server (Outside the App) below for the full permission model.

MCP Server (Outside the App)

Jam SQL Studio runs a local MCP server (Model Context Protocol) that powers the jam-sql CLI and the AI skill. When you run jam-sql add-skill, your coding agent learns to use this CLI to list connections, execute queries, control the UI, and read live app state — all under configurable safety policies. You can also connect any MCP-compatible client (Claude Desktop, LangChain agents, or custom tools) directly to the server for standalone access.

MCP Server Capabilities

The MCP server exposes tools and resources for connections, queries, UI control, and app context. For a live, accurate list, read sql-studio://knowledge/app_capabilities.

Connection & Query Tools

  • connections_list — List saved connections (IDs, names, engines, servers — no secrets: a password, key or SAS signature written into a server is returned as ***, and an Oracle TNS descriptor as its host, port and service name)
  • connections_connect — Connect the app to a saved connection. By default Jam SQL Studio asks you first; see Connecting to a saved connection
  • connections_add — Add a new database connection on the user's behalf (settings-gated; disabled by default). For SQL Server with Microsoft Entra sign-in, Azure Data Explorer and Azure Storage it takes azureEnvironment (AzureCloud, AzureChinaCloud, AzureUSGovernment or a custom environment by id or name); connections_list shows each such connection's environment, so an agent can add another connection in the same one; the approval dialog shows that environment and the hosts the connection's credentials go to (see Azure environments)
  • query_execute — Execute SQL queries (permission-gated: Read-only allows reads, see Read-only check; Confirm prompts for write approval). The SQL may hold several statements, separated by ; (or GO lines on SQL Server), and every result set comes back; see Several statements in one query. Each call runs on its own and cannot keep a transaction open for a later call: if the SQL leaves one open, it is rolled back and the call fails with a message that says so. Put BEGIN and COMMIT in the same call, or run the SQL in a query tab with ui_execute_query, where a transaction stays open until the tab ends it. When the SQL names a table or column that does not exist, the error also names the database the query ran in (on Oracle, the schema) and up to three existing names close to the one written. If the SQL switches database first (USE; on Oracle, ALTER SESSION SET CURRENT_SCHEMA), also inside dynamic SQL such as EXEC('USE …'), sp_executesql or EXECUTE IMMEDIATE, the error names none, and suggests close names only for a table written with its database (on Oracle, its schema) in the name. A query that runs past the agent time limit is stopped; see Time limits and unreachable connections
  • schema_list_tables, schema_list_views, schema_list_procedures, schema_list_functions — List a database's objects (metadata only; allowed even on Block). The optional nameFilter returns only the objects whose name, or schema.name, contains that text, ignoring case, and adds matchCount and totalCount to the reply

Add a connection

When you enable Settings → AI Integrations → Allow AI to add new connections, AI agents (and the jam-sql CLI) can create a new database connection on your behalf. The agent supplies the engine, server, credentials, and optional alias; Jam SQL Studio test-connects first, then persists with the password encrypted at rest. If the test fails, nothing is saved.

Three permission levels:

  • Deny (default): the tool is not available.
  • Confirm each: a dialog opens for each call; you approve or deny.
  • Allow: the tool runs silently — good for batch / unattended workflows.

CLI usage:

echo "$DB_PASSWORD" | jam-sql connection add \
  --engine mssql --alias prod-analytics \
  --server db.example.com --port 1433 \
  --login app_reader --password-stdin \
  --database AnalyticsDb

All engines are supported, including Kusto / Azure Data Explorer — where --server takes the full endpoint URL (an ADX cluster, or the ADX proxy URL of an Azure Monitor / Log Analytics workspace or Application Insights resource) and auth is Entra-based (--auth "Azure CLI", --auth "Service Principal" with --tenant-id, or Interactive Browser sign-in). On Kusto connections agents write KQL; queries and .show commands count as read-only for permission gating.

UI Control Tools

  • ui_open_tab — Open query tabs (allowed even on Block); table explorer tabs require higher permissions
  • ui_focus_tab — Switch to a specific tab by ID
  • ui_set_editor_text — Write SQL content to a query editor (allowed even on Block — no MCP tool will execute that text there, though you can still run the tab yourself); notebook cells are refused on Block
  • ui_execute_query — Run the tab's SQL in the app UI. Gated on the SQL itself, like query_execute: Read-only allows SELECT-class statements, Confirm prompts for write approval
  • ui_close_tab — Close a tab
  • ui_lock_tab / ui_unlock_tab — Lock tabs to prevent conflicts during AI edits
  • ui_check_abort — Check if the user has requested an abort
  • ui_screenshot — Capture a screenshot of the current app window (settings-toggleable)

Table Viewer Tools

  • ui_list_tabs — List all open tabs with IDs, types, titles, and connection info
  • table_refresh — Refresh data in a table explorer tab
  • table_select_row — Select a row by index in a table explorer
  • table_show_row_details — Show/hide row details panel (bottom or side layout)
  • table_set_filter — Apply column filters to a table viewer (IN / NOT IN take a list of values)
  • table_set_sort — Sort table data by column
  • table_set_pagination — Navigate pages of data
  • table_get_snapshot — Get current table state and preview rows
  • table_show_chart — Show/hide chart visualization
  • table_set_chart_config — Configure chart type, axes, and aggregation

Query Editor Tools

  • query_select_row — Select a row in query results (supports multi-result sets)
  • query_show_row_details — Show/hide row details panel
  • query_switch_tab — Switch result tabs (results, messages, plan, chart)
  • query_set_result_display — Set display mode (grid or plaintext)
  • query_execute_with_plan — Execute query with execution plan (estimated or actual)
  • query_get_execution_plan — Get execution plan summary and raw content
  • query_get_messages — Read messages from the messages tab
  • query_get_results — Read query results with optional row limit
  • query_show_chart — Show/hide chart visualization for results
  • query_set_chart_config — Configure chart for query results
  • ui_export_results — Export a results grid to CSV, JSON, Excel, Markdown or SQL INSERT, or stream every row to CSV; works on Query Editor and Table Explorer tabs, and you pick the destination in the save dialog — see Exporting results to a file below.

MetaInfo over MCP

  • schema_get_metainfo — User-declared MetaInfo for one table: loose FK targets, JSON/enum column declarations with cached paths and values, the display/label column, and whether the table itself is marked a reference table (referenceTable: { mode: "cached" | "on-demand" }). Schema tools omit this detail; call it on any table whose metaInfo counts are non-zero.
  • metainfo_declare — Save one MetaInfo declaration (enum column, JSON column, loose FK, or reference-table flag) that the agent judges worth persisting, creating it or updating an existing one on the same target; settings-gated and approval-gated by default — see Declaring MetaInfo below.

schema_list_tables and schema_get_columns include a compact metaInfo counts object (omitted when a table has no user declarations) so agents can cheaply identify which tables need a schema_get_metainfo call — the object also carries refTable when the table itself is flagged a reference table, which alone earns the object even with every other count at zero. Its enumCols counts exactly what schema_get_metainfo returns under enumCols, implicit lookup columns included, so a table that declares nothing but has decodable pairs is still findable.

Marking a table as a reference table makes every other column that points at it an implicit lookup enum with no declaration of its own. Once the app has actually fetched such a column's key→label pairs, they show up back on the referencing table's own enumCols, flagged implicit: true — that flag is opportunistic, present only once the pairs have been fetched, so its absence never proves a column isn't a lookup. It also disappears again if you unmark the target or switch it to on demand: the leftover pairs are a snapshot nothing will refresh, and serving them would decode today's rows with yesterday's names. A reference table flagged on demand never caches pairs at all, so those columns' names only ever resolve live in the UI — an agent has to write its own SQL join to get them. Any lookup-source enum, declared or implicit, also carries a labelColumn when the target table has its own declared display column.

Declaring MetaInfo

After a declaration is saved, the MetaInfo manager and autocomplete hints refresh automatically for that database. You do not need to reopen the editor or wait for a cache timeout.

MetaInfo isn't read-only to agents. When you enable Settings → AI Integrations → Allow AI to declare MetaInfo, an agent that finds something worth persisting — a small FK target it keeps resolving by hand, a categorical column you keep filtering by name, a text column it keeps parsing as JSON — can save it with the metainfo_declare tool: one declaration per call (kind: "enum" | "json" | "loose_fk" | "reference_table"). Names are checked against the live database's metadata before you're ever asked, so a missing table or column is refused up front. Anything that needs to read your data — sampling an enum column's values, reading a reference table's key/label pairs — runs only after you approve, so a proposal you deny costs no queries at all; if the column then turns out not to be categorical, or the table too large to cache, the tool refuses and saves nothing. Deleting a declaration is never offered over MCP.

kind: "json" marks a column as JSON, so the JSON filter operator, the path picker, the cell peek popover and JSON-path loose FKs all work on it. It saves the declaration only — the column's path structure is not scanned, and still comes from browsing the column or from Refresh from DB in the MetaInfo Manager — so the call reads none of your data. Agents are told to propose it only for a column they have actually seen JSON in, never from the column's name. It's refused before you are asked when the column's type can't hold JSON, when the column is already declared (a JSON declaration has nothing else to set), or when a text column sits on PostgreSQL below 16, whose JSON filters need the IS JSON predicate (the server version is read from the version banner alone) — native json/jsonb columns work on any version.

The tool also runs on the connection's own AI permission level: because it reads from the connection to validate what it saves, a connection at Block refuses it outright, whatever this setting says.

Three permission levels (same model as adding a connection):

  • Deny (default): the tool is not available.
  • Confirm each: an approval dialog opens for every proposed declaration, naming exactly what will be saved; a 60-second timeout auto-denies. You approve or deny. Only one proposal is on screen at a time — a second agent asking while you're deciding is refused, not queued behind it.
  • Allow: declarations save silently — useful for unattended workflows.

At Deny, an agent may still mention the setting: if it finds itself redoing the same metadata work by hand in a session — re-writing a join for a relationship your schema doesn't declare, decoding the same status codes, parsing the same text column as JSON — it's told to say so once, name the declaration it would have saved, and leave the decision to you. Once per session, not once per answer.

Either way, the saved entry is badged AI-created in the MetaInfo Manager (or AI-updated if the agent changed an existing user-authored entry) — so you always know a declaration came from an agent. Editing or re-saving it yourself clears the badge; removing it withdraws the declaration entirely. Which of those you reach for depends on the kind: a loose foreign key opens in its editor and a label column can be re-picked from the enum details, so both clear by editing. An enum declaration and a reference-table flag have no edit dialog today — remove them and declare again. Nothing in your actual database changes; this only writes to the local, per-database MetaInfo file.

CLI usage:

jam-sql call metainfo_declare kind=enum connectionId=abc123 database=mydb \
  schema=dbo table=Orders column=status
jam-sql call metainfo_declare kind=json connectionId=abc123 database=mydb \
  schema=dbo table=Orders column=metadata

Exporting results to a file

Ask an agent to “export this to Excel” or “save these rows as CSV” and it can do it with the ui_export_results tool, on a Query Editor or Table Explorer tab. It runs the same export the grid’s own export menu runs, so the file is the one you would have produced yourself — a real Excel workbook, dialect-aware INSERT statements with SQL Server IDENTITY handling, spatial columns decoded to WKT.

The agent does not choose where the file goes. The app opens its usual save dialog, you pick the destination, and the tool has no path parameter to bypass it — writing a file anywhere on your machine is not a database capability, and none of the permission levels speaks about your filesystem. Dismissing the dialog cancels the export and the agent is told you declined.

  • Formats — csv, json, xlsx, markdown, sql (INSERT statements).
  • Scope — by default the rows the grid holds. For a large windowed result set an agent can pass scope: "all-rows" to stream every row, the same path as “Export All to CSV” (CSV only, Query Editor only — Table Explorer pages through a table and has no all-rows export).
  • Which result set — the active one, unless the agent passes allResultSets: true (Excel and JSON only).

Refused for connections whose AI permission level is Block: an export is a bulk read of that connection’s data, and where the bytes land doesn’t change what was read.

CLI usage:

jam-sql call ui_export_results tabId=tab-1 format=xlsx
jam-sql call ui_export_results tabId=tab-1 format=csv scope=all-rows

Database Blueprint Tools

Manage Database Blueprints (folders of .sql files kept in sync with a linked database) from AI agents, under the same permission model as SQL writes:

Read-only (permission level read-only or confirm; denied at block):

  • blueprint_list — List registered blueprint folders with label, engine, and linked-DB count
  • blueprint_get — Full metadata, object counts, and on-disk drift for one blueprint folder/link
  • blueprint_preview — Per-file change summary for the pending refresh (no write)

Write-gated (denied at block/read-only; in-app approval required at confirm):

  • blueprint_attach — Register an existing blueprint folder (e.g. after git clone)
  • blueprint_create — Materialize a database as a new blueprint in an empty folder
  • blueprint_refresh — Re-emit DDL and data sidecars from the linked DB into the folder

DB-mutating (confirm-only; approval dialog shows the generated SQL before execution):

  • blueprint_apply_schema — Folder→DB schema sync: headless schema compare, generates SQL, shows for approval, executes
  • blueprint_sync_data — Folder→DB row sync: per-table data compare, two-phase script (deletes then upserts), shows for approval, executes

CLI equivalents: jam-sql blueprint list|get|preview|attach|create|refresh|apply-schema|sync-data. See Database Blueprint → AI-managed blueprints for details.

An agent cannot drop an object just by taking the default.

schema_compare_generate_script called without selectedKeys selects every changed object except the ones that exist only on the target — the objects whose only possible script is a DROP. That is the same rule Jam applies to its own one-click Apply to linked DBs batch, and for the same reason: neither a batch nor an agent has the results tree in front of it, so whatever the default picks is what one action destroys.

Nothing is hidden. The withheld keys come back in withheldDestructiveKeys, the count comes back in warnings, and an agent that has told you which objects would be destroyed can pass those keys in selectedKeys to script the DROP deliberately. Jam may still refuse them — if they were never in the comparison's scope, if a Database Blueprint excludes them, or if the script would leave the database empty — and the tool result says which.

blueprint_apply_schema has no key parameter at all, so it can never script a whole-object DROP. It can still drop a column, index or constraint on a table the blueprint manages, because that table's .sql file defines its shape.

This is stronger than what the desktop app allows you, and deliberately so: in the Schema Compare tab you can tick a target-only row yourself and generate its DROP. The whole-schema drop confirmation is the other place the two differ — it exists only in the desktop Script Preview dialog, so an agent that hits it cannot confirm past it and should send you to the app rather than retrying.

Dashboard Tools

Manage SQL Dashboards from AI agents. Dashboards are workspace artifacts, not database writes — every tool except dashboard_list is denied only at permission level block, and tile queries themselves still run under the read-only execution policy in the app:

  • dashboard_list — All dashboards with their tiles (ids, titles, tile types), revision, and last-updated time
  • dashboard_create — New empty dashboard; returns a structured free-limit error at the free-plan cap
  • dashboard_add_tile — Add one tile from full tile JSON (chart/stat/table/pivot/map/note; id, layout, and refresh are generated when omitted) or from a built-in template id plus a connection
  • dashboard_update_tile — Shallow-merge a patch (title, layout, refresh, SQL, thresholds, …) onto one existing tile
  • dashboard_refresh — Refresh an open dashboard's query tiles and report per-tile success or error. An agent refresh runs read tiles only — a write tile refuses the whole refresh, whatever scheduled-refresh trust it was granted (that trust belongs to the app's own scheduler, not to an agent)

Every change an agent makes goes through the same repository as the UI, so the open app updates live — the switcher, the Object Explorer node, and any open dashboard tab. CLI equivalent: jam-sql call dashboard_<tool>.

Azure Storage Tools

Browse and manage an Azure Storage connection. At block every tool call on that connection is denied (storage_transfer_status leaves out its jobs); writes are denied at read-only and use a separate in-app approval at confirm:

  • storage_list_containers — One page of the account's blob containers, or with service: "file" its file shares, with a continuation token
  • storage_list — One page of blobs and virtual folders under a container or prefix (recursive flattens the tree), or of the files and folders in one file-share folder (one folder per call). On an account with a hierarchical namespace it also takes a Data Lake directory, { kind: "hnsPath", fileSystem, path }, and answers the same items with owner, owning group and permissions
  • storage_get_properties — Properties, metadata and tags of one blob or container; quota, usage, protocol and recoverability of one file share; size, times and SMB / NFS details of one share folder or file
  • storage_account_info — Account name, kind, hierarchical-namespace state, attachment scope, and per-service availability
  • storage_download — Download one or more blobs, prefixes, or a container, or files and folders of one file share (optionally a snapshot of it). You choose the destination in a save/folder dialog; the agent never chooses it
  • storage_transfer_status — Read visible transfer progress and recovery state; jobs on blocked connections are omitted
  • storage_upload — Upload one local file or folder into a container, prefix, file share or share folder after the app shows its source and destination for approval
  • storage_delete — Delete approved blob, prefix, multi-item, or container resources (blob snapshots are included), or files and folders of one file share, or one whole share with its snapshots
  • storage_create_container — Create one container and return immediately after the service acknowledges it
  • storage_find — Find blobs, Data Lake paths, or file-share files and folders by part of a name, * / ? wildcards or an extension under a location, beyond the service's prefix filter. Each call returns at most maxResults matches after scanning at most maxScanned items; pass its continuationToken back with the same arguments to continue. When a read fails partway, the call returns the matches found so far with a token that retries the failed read. A read
  • storage_list_queues — One page of the account's queues with approximate message counts
  • storage_peek_messages — Read the next messages of a queue without consuming them or changing their visibility
  • storage_send_message — Add one message to a queue after approval
  • storage_receive_messages — Receive the next messages after approval; they stay hidden for the visibility timeout and become visible again after it unless they are deleted or expire first. The result carries neither the Azure pop receipt nor the app's receipt handle
  • storage_clear_queue — Delete every message in a queue after approval; the removed count is approximate
  • storage_generate_sas — Generate an account, service, stored-policy or user-delegation SAS after approval. The token is shown only in the app's SAS result panel; the agent receives the enforced permissions, dates, protocol, IP range and scope, and the resource URL without any query string. A Data Lake directory ({ kind: "hnsPath", fileSystem, path, isDirectory: true }) gets a directory SAS limited to that directory and everything under it; the file-system root gets a container SAS
  • storage_query_entities — One page of Table entities as tagged EDM values, with an optional OData filter (at most 15 comparisons) and column projection; pass the returned continuation token back as cursor for the next page. Azure reports no total
  • storage_count_entities — Count the entities of a table, or those matching an OData filter, by reading every page with only the PartitionKey (no entity data). Read-only. The number is what the walk read, not a snapshot: entities written while it runs may or may not be counted. maxSeconds (default 60, at most 300) bounds the walk; an unfinished count returns complete: false with the number read so far
  • storage_copy_table — Copy the entities of a table (optionally only those matching an OData filter) into a table on the same or another Azure Storage connection, as a Transfers job you approve first. ifExists chooses what happens to an entity the target already has: skip (default), merge, replace or fail (stop at the first entity that cannot be written). copyMetaInfo also copies the table's MetaInfo declarations; it follows Allow AI to declare MetaInfo (Deny refuses the request, Confirm each is covered by the copy's approval). With createTarget a missing target table is created: the approval names the new table and the target storage account (and its Azure environment outside public Azure), and nothing is created until you approve. Answers with the counts copied, skipped, failed, uncertain and not sent
  • storage_get_acl — Owner, owning group, permission string and the access and default ACL entries (masks included) of one ADLS Gen2 path, addressed as { fileSystem, path }
  • storage_set_acl — Change the ACL of one ADLS Gen2 path after approval: replace it, merge entries or remove named entries, optionally with a new owner or owning group. With recursive: true the change is applied to a directory and everything under it as a job in the Transfers drawer, and the call waits for it; the answer lists up to 100 failed paths and counts the rest
  • storage_create_directory — Create an ADLS Gen2 directory, and any missing parent directories, after approval; refused when a file or directory already exists there
  • storage_move_path — Rename or move an ADLS Gen2 file or directory after approval, within or across file systems. It never overwrites, and it is refused when the source changed after the check that preceded the approval. An unfinished move returns a pendingMoveId to continue it; continuing a move whose outcome is unknown checks both locations first and reports it as moved only when that check proves it
  • storage_copy — Copy blobs, folders or whole containers server-side after approval: within a container, across containers, or to another connection or storage account (Data Lake included). Both connections are checked; the approval lists every source and what is written: the new name when one is given, and each destination container with what happens to it. If a container appears or disappears after the approval, nothing is started. Archived blobs are copied to the tier you name, keep their metadata, and are then rehydrated by Azure
  • storage_move — Move blobs or folders after approval: each is copied, the copy is checked, and only then is the original deleted, while it is still the version that was copied. An original that changed, has snapshots or is leased is kept and reported, and so is one whose copy another client changed or leased before the delete. If you lower the AI access of either connection while a copy or move the agent started is running, its remaining items stop and the originals are kept. Containers cannot be moved. Within one Data Lake connection the move is Azure's own rename
  • storage_write_entities — Create, merge, replace or conditionally delete Table entities after approval. Updates and deletes require a concrete ETag; the approval shows the table and the operation totals and lists each targeted PartitionKey and RowKey once, never property values. Creating or deleting a table stays in the app
  • storage_create_share — Create a file share (name, optional quota, SMB or NFS) after approval, from a connection to the storage account
  • storage_set_share_quota — Change a file share's quota after approval; the approval shows the old and the new size. Just before the write, the app reads the quota again and compares it with the old size, and writes nothing if it differs; Azure has no condition for a quota change, so a change made in the moment between that check and the write is not detected
  • storage_share_snapshots — List a share's snapshots (a read), or create or delete one after approval
  • storage_mount_command — Mount commands for a share as text (Windows, macOS and Linux for SMB; Linux for NFS), with a placeholder where the account key goes
  • storage_lease — Acquire (infinite by default, or 15–60 seconds), renew, release or break (at once, or with a break period of up to 60 seconds) the leases of up to 100 blobs, containers and Data Lake folders after approval. The approval says what the action does — an infinite lease stays held after the app quits, a break takes the lease from whichever client holds it — and lists every target. A lease the agent acquires is held by Jam SQL Studio, which sends it with its own writes; renew and release act only on leases the app holds. The answer gives one line per target (acquired, renewed, released, broken, breaking, not leased, uncertain or refused, with the reason) and whether the app holds the lease now; it never contains a lease ID
  • storage_list_history — The current version, earlier versions and snapshots of one blob (soft-deleted ones with includeDeleted), or the deleted copies of one Data Lake path with their deletion IDs. storage_list also takes include flags for deleted blobs, versions, snapshots and blobs without a current version, and storage_list_containers takes includeDeleted
  • storage_snapshot — Create a read-only snapshot of a blob after approval; with ifMatch it is refused when the blob changed since it was read
  • storage_restore — After approval, restore soft-deleted blobs or Data Lake paths (exact entries, everything under folders, or a deletion-time window) as a Transfers job the call waits for, or restore a deleted container or file share under its own name, or promote a version or snapshot to be the current blob (a copy job the call waits for; by default a snapshot keeps the current content first). Azure restores every soft-deleted version and snapshot of a blob together, and refuses a container or share restore for about 30 seconds after the delete
  • storage_list_disks — The managed disks and disk snapshots of one resource group of an Azure subscription connection: name, type, size, SKU, state, attached VM, OS type, region, zone and creation time. Read-only
  • storage_get_disk — The properties of one managed disk or snapshot, including encryption, network access policy and data access authentication. Read-only
  • storage_create_disk_snapshot — Create an incremental (the default) or full snapshot of a disk or snapshot in its resource group after approval; a taken name is refused
  • storage_copy_disk — Create a new disk as a copy of a disk or snapshot after approval, in the source's region or another (location; the source gets read access while the copy runs), with the chosen SKU and zone and the source's OS, Entra and network settings; the call waits for the copy job
  • storage_upload_disk — Create a new disk from a fixed VHD file on this computer after approval, with the chosen region, SKU, zone and optional OS type, Hyper-V generation, architecture and Entra data access. A dynamic VHD, a VHDX or a size Azure cannot use is refused before the approval; the call waits for the upload job
  • storage_download_disk — Download a disk or snapshot as a VHD file. The approval says read access is granted for up to 24 hours and that the app revokes the access it granted when the download ends (access granted outside the app stays as it is); you then choose the destination in a save dialog, and the call waits for the transfer. Never returns the access URL
  • storage_delete_disk — Delete a disk or snapshot after approval. A disk attached to a VM, or one whose access is granted, is refused before any dialog

The approval dialog asks what the write does (for example Delete 3 storage items?), shows the tool name as detail, and marks whether the write removes, changes or adds data. It lists every target the write touches once, in full, in a list you scroll, above a short summary of the consequences; a line saying that access widens comes first. Deny has the keyboard focus when the dialog opens. A call can name at most 1,000 items. A container or share deletion is listed first and says that the whole container and all its blobs are deleted, a folder deletion says it includes everything under the folder, and an upload shows its destination folder and what happens to existing blobs with the same name. A folder given without a trailing slash is that folder: logs means logs/ in the dialog and in the write, so it never also matches logs-2026.csv. An upload's destination folder is used exactly as the dialog shows it; a folder that starts with / or contains //, a backslash, or a . or .. folder name is refused before the dialog opens. Only one storage write-approval dialog is open at a time; a second storage request waits until the first is answered, and a request that cannot be shown before its timeout is reported to the agent as not shown rather than as denied. Reloading or closing the app window closes a pending storage approval without writing anything, and the next waiting request opens. The approval response is correlated to the exact pending request; denying or dismissing it performs no write. After approval, Jam SQL Studio rechecks the current connection, read-only flag, and attachment scope. UI and MCP mutations refresh the matching Object Explorer branch even when no storage browser tab is open.

For the ADLS Gen2 tools the app reads the path before it asks, and the approval is built from that read: storage_set_acl lists every entry of the resulting ACL, the mask and each change in effective permissions (widened ones are marked), and the write is refused without changing anything when the path was replaced after that read (Azure checks the path's version) or when the access control, read again and compared just before the write, differs from it. Azure has no condition for access-control changes, so a change made in the moment between that check and the write is not detected and is overwritten. The app never recalculates a mask on the agent's behalf: a merge that adds or changes a named user or group must include that scope's mask. A recursive change cannot be made conditional by Azure, so its approval says exactly what is checked: the directory's version is read when the approval is built and checked again right before the first batch, the moment between that check and the first batch is not covered, each later batch checks that the directory is still the same one (for a whole file system the approval says instead that a deleted and re-created file system cannot be detected), and paths added, removed or changed under it while the job runs get the change as they are when their batch runs. A recursive removal also says that Azure recalculates the mask of every ACL it removes an entry from, and so does a recursive merge that changes a scope's entries without that scope's mask; a recursive merge that sets a scope's mask says that this mask replaces the mask of every path. Entries are named by object ID, with the user principal name beside it when the app could match it to that ID. The move approval names the source (with the version that was read) and the destination, which must not exist. An unfinished move is checked again before anything is sent, and the app reports that nothing was moved only a minute after an answer was lost, because Azure can still complete the request until then. Every approval also lists the complete set of paths the call touches; for a recursive change that is the directory and everything under it, since the individual paths are not known in advance. See Azure Storage → ADLS Gen2 for the full rules.

For storage_generate_sas the approval names the resource, the SAS kind, each permission in words and the validity window, with a warning for an account SAS, write or delete permissions, listing, or a token valid for more than seven days. A stored-policy SAS shows the permissions and dates the policy gives the token, and the policy is read again just before signing. The tool is refused on a read-only connection and at read-only, even for a read or list token. See Azure Storage → AI agents for the full rules.

An agent can also open the storage browser with ui_open_tab and the storage-explorer tab type, and add a storage connection with connections_add (engine: "azurestorage"). When its connectionString is an Azurite string, the keys the app recognises but does not use (a FileEndpoint, since Azurite has no Files service, and EndpointSuffix) are listed in the result's unusedKeys. Because these connections do not run SQL, query_execute and the query / table-explorer / notebook tab types refuse them with "Azure Storage connections have no query language; use the storage browser or the storage_* tools." CLI equivalent: jam-sql storage containers|ls|props|info|download; the queue tools, the Table entity tools, the file-share tools, the ADLS Gen2 tools, storage_lease and storage_generate_sas are called with jam-sql call.

Context Resources (Read-Only)

  • workspace_snapshot — Active workspace state
  • connections_snapshot — Saved connections with current status
  • tabs_snapshot — Open tabs with IDs, types, titles, active state
  • editor_snapshot — Active editor buffer with SQL content
  • results_snapshot — Latest query results metadata and preview rows
  • selection_snapshot — Currently selected explorer item

Knowledge Resources

  • app_manifest — App version, platform, enabled features
  • app_capabilities — Supported workflows and current limitations
  • app_user_guide — How-to documentation for using the app

Supported AI Tools

Any AI tool that supports MCP or HTTP can connect to Jam SQL Studio:

  • Claude Code (recommended) — Native HTTP support via .mcp.json (project) or ~/.claude.json (user), or use claude mcp add
  • Claude Desktop — Over stdio with npx -y @jamsql/mcp (Node.js 18+; see setup)
  • Codex CLI — Configure in ~/.codex/config.toml or use codex mcp add
  • OpenCode — Environment variable configuration
  • GitHub Copilot — Via MCP extension or custom integration
  • Custom agents — Built with LangChain, AutoGen, or any HTTP client

Setting Up MCP Server

  1. Open Jam SQL Studio and go to Settings → AI Integrations
  2. Enable MCP Server
  3. Copy the Endpoint URL (e.g., http://127.0.0.1:14507/mcp)
  4. Copy the Bearer Token (click "Show" then "Copy")
  5. Configure your AI tool with the endpoint and token (see examples below)
The AI Integrations settings panel showing MCP server configuration, endpoint URL, and token management.
The AI Integrations settings panel showing MCP server configuration, endpoint URL, and token management.

Manual MCP Setup (per-tool configuration)

If you prefer to configure the MCP connection manually for a specific tool, expand the relevant section below:

Claude Code CLI

Claude Code can connect to Jam SQL Studio via MCP to query your databases directly from the terminal.

Step 1: Enable MCP Server in Jam SQL Studio

  1. Open Jam SQL Studio
  2. Go to Settings (gear icon) → AI Integrations tab
  3. Toggle Enable MCP server to ON
  4. Copy the Endpoint URL (e.g., http://127.0.0.1:14507/mcp)
  5. Click Show next to the token, then Copy the token

Step 2: Configure Claude Code

You have two options for configuring MCP servers:

Option A: User scope (available across all projects) — create or edit ~/.claude.json:

{
  "mcpServers": {
    "jam-sql": {
      "type": "http",
      "url": "http://127.0.0.1:14507/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Option B: Project scope (shared with your team) — create .mcp.json in your project root:

{
  "mcpServers": {
    "jam-sql": {
      "type": "http",
      "url": "${JAM_SQL_MCP_ENDPOINT:-http://127.0.0.1:14507/mcp}",
      "headers": {
        "Authorization": "Bearer ${JAM_SQL_MCP_TOKEN}"
      }
    }
  }
}

Project-scope config supports environment variable expansion with ${VAR} syntax.

Option C: Use the CLI to add the server directly:

claude mcp add --transport http jam-sql http://127.0.0.1:14507/mcp \
  --header "Authorization: Bearer YOUR_TOKEN_HERE" \
  --scope user

Step 3: Verify Connection

Run Claude Code and check that the server is connected:

claude mcp list

Or inside Claude Code, type /mcp to see connected servers.

Codex CLI

OpenAI's Codex CLI uses a TOML configuration file for MCP servers.

Step 1: Enable MCP Server in Jam SQL Studio

  1. Open Jam SQL Studio
  2. Go to Settings (gear icon) → AI Integrations tab
  3. Toggle Enable MCP server to ON
  4. Copy the Endpoint URL (e.g., http://127.0.0.1:14507/mcp)
  5. Click Show next to the token, then Copy the token

Step 2: Configure Codex

Add the MCP server to ~/.codex/config.toml:

[mcp_servers.jam-sql]
url = "http://127.0.0.1:14507/mcp"
bearer_token_env_var = "JAM_SQL_MCP_TOKEN"

Then set the token in your shell profile (~/.zshrc or ~/.bashrc):

export JAM_SQL_MCP_TOKEN="YOUR_TOKEN_HERE"

Alternative: Use the CLI to add the server:

codex mcp add jam-sql --url http://127.0.0.1:14507/mcp

Step 3: Verify Connection

Inside Codex, type /mcp to see active MCP servers.

Troubleshooting: If Jam SQL's AI Chat Sidebar shows unexpected argument '--json', your Codex CLI is incompatible with session resume. Update Codex CLI and confirm codex exec resume --help lists --json.

Claude Desktop

Claude Desktop starts MCP servers as local commands that talk over stdio, so it connects through the @jamsql/mcp package. Turn on Enable MCP server in Settings → AI Integrations and run jam-sql pair once, then add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "jam-sql": {
      "command": "npx",
      "args": ["-y", "@jamsql/mcp"]
    }
  }
}

Quit and reopen Claude Desktop; "jam-sql" appears in its tools menu. No endpoint, token or Node.js 20 install is needed. Overrides and troubleshooting: Claude Desktop and other stdio clients.

Other Tools / Direct HTTP

Any tool that supports HTTP can connect to Jam SQL Studio's MCP server.

Direct HTTP Access

Make HTTP POST requests to the MCP endpoint with JSON-RPC 2.0:

curl -X POST http://127.0.0.1:14507/mcp \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Environment Variables (for custom integrations)

If your tool supports environment-based config:

export JAM_SQL_MCP_ENDPOINT="http://127.0.0.1:14507/mcp"
export JAM_SQL_MCP_TOKEN="YOUR_TOKEN_HERE"

LangChain / AutoGen / Custom Agents

Use any MCP client library or make direct HTTP calls to the endpoint. The server implements the standard Model Context Protocol specification.

Claude Desktop and other stdio clients: @jamsql/mcp

Claude Desktop, and any MCP client you configure with a command instead of a URL, starts each MCP server as a local process and talks to it over stdin/stdout. The @jamsql/mcp npm package is that process for Jam SQL Studio: it forwards every MCP message to the app's local endpoint and passes the answers back. Its source is public at github.com/jamsql/mcp (MIT). It reads the endpoint and the token the same way the jam-sql CLI does, so the client configuration holds no port and no token. It runs on Node.js 18 or newer. Claude Desktop starts it with the npx of the Node.js installed on your computer: its built-in Node.js runs only installed extensions, not the entries of claude_desktop_config.json. If node --version does not answer in a terminal, install Node.js from nodejs.org first.

Add to Claude Desktop from Settings

In Settings → AI Integrations → Quick Setup, the Claude Desktop row shows whether Claude Desktop is installed and whether Jam SQL Studio is already one of its MCP servers. Add to Claude Desktop opens a confirmation that names the file and the entry it adds under mcpServers:

"jam-sql-studio": {
  "command": "npx",
  "args": ["-y", "@jamsql/mcp"]
}

On Windows the entry is "command": "cmd" with "args": ["/c", "npx", "-y", "@jamsql/mcp"]: npx is a batch file there, and a program that starts it directly can fail with spawn npx ENOENT.

  • Every other server and setting in the file stays as it is. Jam saves a copy of the current file as claude_desktop_config.json.bak before it writes, readable by the same people as the file itself; each Add or Remove replaces that copy.
  • The file keeps its permissions, owner and group. If Jam cannot give the new file the same owner or group (a group you are not a member of, for example), only you can read it. If it is a symbolic link (a config kept in a dotfiles folder, for example), Jam changes the file the link points to and the link stays.
  • If Claude Desktop or an editor saves the file while Jam is writing it, Jam merges its change into the saved version instead of overwriting it. If the file keeps changing, Jam leaves it as it is and asks you to try again.
  • If the file is not valid JSON, Jam does not change it and says so; fix or move the file, then try again.
  • If ~/.jamsql/credentials does not hold the app's current token, Jam saves it there (the same file jam-sql pair writes), so you do not need to pair from a terminal.
  • Any server that already runs @jamsql/mcp, under any name, counts as added. Remove takes those entries out again, with the same backup.
  • Afterwards, quit Claude Desktop completely (Cmd+Q on macOS, the tray icon's Quit on Windows) and open it again. The MCP server must be on in Jam while Claude Desktop uses it.

Where Jam looks for the file: on macOS ~/Library/Application Support/Claude/; on Windows %APPDATA%\Claude\, or, for the packaged installer that claude.ai and the Microsoft Store use, %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\ or %LOCALAPPDATA%\Claude-Data\claude_pzs8sxrjxfjjc\ when Claude Desktop has moved its profile there; on Linux ~/.config/Claude/, and the row appears only when that folder exists. The confirmation always shows the exact path.

To set it up by hand instead:

  1. In Jam SQL Studio, turn on Settings → AI Integrations → Enable MCP server.
  2. Pair once from a terminal with jam-sql pair and approve the code in the app (see Pairing). The token is saved in ~/.jamsql/credentials. Add to Claude Desktop saves it for you.
  3. Add the server to your client and restart the client:

Claude Desktop — claude_desktop_config.json; Cursor — ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "jam-sql": {
      "command": "npx",
      "args": ["-y", "@jamsql/mcp"]
    }
  }
}

VS Code — .vscode/mcp.json:

{
  "servers": {
    "jam-sql": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jamsql/mcp"]
    }
  }
}

Cursor and VS Code can also use the HTTP endpoint directly (see above). The npx entry keeps working when the app's port changes, because the bridge looks the port up each time the app restarts.

How the bridge finds the app

  • Endpoint — from ~/.jamsql/mcp-discovery.json, which Jam SQL Studio writes when it starts. The file records the app's process id, so a file left behind by a closed or crashed app is ignored.
  • Token — from ~/.jamsql/credentials, which jam-sql pair writes.
  • Overrides — JAMSQL_MCP_URL and JAMSQL_MCP_TOKEN in the client's env block take precedence over both files; the CLI's names JAM_SQL_MCP_ENDPOINT and JAM_SQL_MCP_TOKEN work too. Use them to skip pairing with the token from Settings → AI Integrations. JAMSQL_MCP_DEBUG=1 logs each forwarded method name.
{
  "mcpServers": {
    "jam-sql": {
      "command": "npx",
      "args": ["-y", "@jamsql/mcp"],
      "env": {
        "JAMSQL_MCP_URL": "http://127.0.0.1:14507/mcp",
        "JAMSQL_MCP_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

When the app restarts

Restarting Jam SQL Studio, or switching its MCP server off and on, ends every MCP session. The bridge opens a new session with the client's original settings and retries the request, so the client keeps working without being restarted. If the app comes back on another port, the bridge reads the new port from the discovery file. A request that already reached the app is never sent twice: if its answer is lost, the client gets an error instead.

Troubleshooting the bridge

The bridge writes its messages to stderr, which the client keeps in its MCP log (Claude Desktop: ~/Library/Logs/Claude/ on macOS, the logs folder beside claude_desktop_config.json on Windows). A request it cannot forward gets a JSON-RPC error with the same message. The token is never printed.

MessageWhat to do
Jam SQL Studio is not runningStart the app and keep it open while the client uses it.
Its MCP server is turned offSettings → AI Integrations → Enable MCP server.
Not paired with Jam SQL StudioRun jam-sql pair, or set JAMSQL_MCP_TOKEN.
Rejected the pairing tokenThe token was regenerated in the app. Run jam-sql pair again, or update JAMSQL_MCP_TOKEN.
Could not reach Jam SQL Studio's MCP serverCheck JAMSQL_MCP_URL, and that the MCP server is enabled.

To check the setup from a terminal, send one initialize request; the app's answer, or the error naming what is missing, is printed:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"terminal","version":"0"}}}' | npx -y @jamsql/mcp

On Windows, use "command": "cmd" with "args": ["/c", "npx", "-y", "@jamsql/mcp"] (the form Add to Claude Desktop writes there): npx is a batch file on Windows, and a client that starts it directly can fail with spawn npx ENOENT. Earlier Claude Desktop setups used the mcp-remote proxy with a copied endpoint and token, which needed Node.js 20 or newer; replace that entry with the @jamsql/mcp one above.

Troubleshooting

  • Connection refused? Make sure Jam SQL Studio is running and MCP server is enabled in Settings.
  • 401 Unauthorized? Double-check your token — it must match exactly (no extra spaces).
  • Port mismatch? The port number may vary. Copy the endpoint URL from Jam SQL Studio settings (or click the MCP row in the AI menu — it shows 127.0.0.1:<port>).

Security Model

The MCP server binds to 127.0.0.1 only (localhost). All requests require a valid Bearer token. No queries run by default; you can allow Read-only mode (reads only: SELECT, EXPLAIN, SHOW, PRAGMA and SQL Server's read-only system procedures) or Confirm mode, where each write query requires your in-app approval. Passwords are never exposed. Every tool call is recorded in AI activity.

Permission Levels

Configure the AI policy in Settings to control what the MCP server can do:

  • Block (default) — No query execution; allows safe query-tab editing (open tab + set SQL text) and schema introspection
  • Read-only — Allow strict read-only queries only (SELECT, EXPLAIN, SHOW, PRAGMA and the statements listed under what Read-only runs — recommended)
  • Confirm — Allow write queries only after in-app approval (each write prompts you)

Where there is SQL to judge, the level is judged on the SQL, never on the tool. Asking the app to run a tab or a notebook cell (ui_execute_query, query_execute_with_plan in actual mode, notebook_run_cell, notebook_run_all) is classified exactly like query_execute — so Read-only means read-only whichever route the agent takes. The approved text is also the text that runs: each statement is compared against what was checked at the moment it would execute, so a tab or cell rewritten in between — while an approval dialog is open, or midway through a notebook_run_all — is refused instead of executed unchecked. Nothing runs whose text was not classified for that request. The same holds for where it runs: the check, the approval dialog and its row counts are for the connection and database the tab points at, and a tab you switch to another connection or database before the statement is sent is refused, so the agent reads the tab again and asks once more.

Several statements in one query. query_execute (and jam-sql query) accepts a batch such as SELECT COUNT(*) FROM orders; SELECT COUNT(*) FROM customers and returns one result set per statement. At Read-only the batch runs only when every statement in it is a read: each statement is checked the same way a single query is, and one that is not a read — a write, DO, ATTACH, a PL/SQL block, or a SET or DECLARE other than those Read-only runs — refuses the whole batch with a message that names it. Nothing in a refused batch runs. At Confirm a batch of reads runs without a dialog, and a batch with a write asks once for the whole script. ui_execute_query (the whole tab) and notebook_run_cell / notebook_run_all (each cell) are checked the same way. query_execute_with_plan takes one statement, because the plan capture runs the tab's text behind EXPLAIN.

Two things no permission level allows

The levels above describe what an agent may do to your databases. Two notebook capabilities are not database operations at all, so there is no level that grants them — they are refused at Confirm just as firmly as at Block:

  • Running a JavaScript cell. A notebook JavaScript cell runs a program on your computer, not a query against your database. An agent can add, edit and read one; only you can run it. That holds however the request arrives — notebook_run_cell, notebook_run_all, or ui_execute_query on a notebook — and the cell's type is checked at the moment it would run, so converting a cell to JavaScript after it was approved changes nothing.
  • Choosing where a notebook is saved. notebook_save writes back to the file the notebook was opened from or last saved to. A notebook you have never saved is refused, and you pick the location yourself through the save dialog.

Text the classifier cannot take apart — several statements in one tab, an unmatched quote, or a trailing -- comment that reads as a second statement — is refused at Read-only and Confirm rather than approved. It is not necessarily a write; Jam SQL Studio simply cannot verify what it would run, and a prompt that says "write query" about two SELECTs is one people learn to click through. Split the statements into separate tabs or cells, or run them yourself.

Read-only checks the whole text, not only its first word. SQL Server needs no ; between statements, so SELECT 1 DELETE FROM t is a read followed by a delete, and on PostgreSQL WITH d AS (DELETE … RETURNING …) SELECT … starts like a read. So a query is refused at Read-only when its code — everything outside string literals and comments, judged with the connection's own engine rules — contains any of:

  • a write or DDL keyword: INSERT, UPDATE, DELETE, MERGE, UPSERT, CREATE, ALTER, DROP, TRUNCATE, RENAME, GRANT, REVOKE, DENY, or INTO (which also covers SELECT … INTO and MySQL INTO OUTFILE / DUMPFILE);
  • a procedure call, lock or transaction statement: EXEC, EXECUTE, CALL, LOCK, UNLOCK, COMMIT, ROLLBACK, SAVEPOINT, plus FOR UPDATE / FOR SHARE;
  • a server action: KILL, SHUTDOWN, BACKUP, RESTORE, DBCC, BULK, OPENROWSET, OPENDATASOURCE, OPENQUERY;
  • on SQL Server, the statements that run when they simply follow a query, or follow it inside an IF or WHILE or after a label — BEGIN (BEGIN TRAN), SAVE, CHECKPOINT, RECONFIGURE, WAITFOR, SETUSER, OPEN, WRITETEXT, UPDATETEXT, ADD (ADD SIGNATURE, ADD SENSITIVITY CLASSIFICATION), END CONVERSATION, ENABLE / DISABLE TRIGGER, RECEIVE, SEND ON CONVERSATION, MOVE / GET CONVERSATION, IF, WHILE — and the lock hints UPDLOCK, XLOCK, TABLOCK, TABLOCKX, HOLDLOCK, SERIALIZABLE, REPEATABLEREAD;
  • a sequence advance (nextval(), seq.NEXTVAL, NEXT VALUE FOR), or a call of a built-in that writes, locks, sleeps or reaches outside the database — such as setval(), pg_sleep(), pg_terminate_backend(), pg_read_file(), the PostgreSQL server-file functions (pg_ls_dir() and the other pg_ls_*(), pg_stat_file(), pg_export_snapshot(), pg_log_backend_memory_contexts()), the PostgreSQL large-object writers (lo_put(), lowrite(), lo_create()), server-state functions (pg_notify(), pg_switch_wal(), replication-slot and stats-reset functions) and index-maintenance functions (brin_summarize_new_values(), brin_summarize_range(), brin_desummarize_range(), gin_clean_pending_list()), the SQL Server file readers (fn_xe_file_target_read_file(), fn_get_audit_file(), fn_get_audit_file_v2(), fn_trace_gettable(), and the undocumented fn_dump_dblog(), fn_dump_dblog_xtp(), fn_full_dblog(), fn_filelog() and fn_MSxe_read_event_stream()), the MySQL replication waits (MASTER_POS_WAIT()), Oracle HTTPURITYPE(), GET_LOCK(), SLEEP(), LOAD_FILE(), load_extension(), readfile(), fsdir(), or any Oracle DBMS_* / UTL_* package.

The check reads the SQL the way the connection's own engine does. A second statement after the first counts whether it is separated by a ;, by a SQL Server GO, by an Oracle / line or a MySQL DELIMITER directive, or by nothing at all (SQL Server runs a statement that simply follows another), and the separator line's spacing is read the way the engine reads it. Comments are read per engine too: SQL Server and PostgreSQL nest block comments and end a -- comment at a carriage return, PostgreSQL dollar-quote tags may be non-ASCII ($é$…$é$), and a MySQL version-gated comment (/*!99999 … */, which an older server ignores) is checked both as run and as ignored — so a write hidden behind any of them is still found. A keyword counts even when it is glued to a number (SELECT 1DELETE FROM t is two statements on SQL Server, as is SELECT 1eADD …, because SQL Server reads 1e as a number; PostgreSQL 14 and earlier read SELECT 1INTO t as SELECT 1 INTO t; a MySQL identifier may begin with a digit, so 123update there is a column name) or when a function name is quoted. The SQL Server statement words above count only where they start a word of their own: @add and @begin are variables, and 0x0ADD is a binary value. On SQL Server, a number that ends in e right before -- (SELECT 1e--1 DELETE FROM t) is refused: SQL Server reads the first dash as part of the number and the second as a minus sign, not as the start of a comment, so the DELETE would run. Put a space before the --. A money value takes one sign the same way: $-- (or £--, €-- and the other currency signs SQL Server accepts) is the money $- and a minus sign, also right after a number (SELECT TOP 1$-- 1 DELETE FROM t), so SELECT $-- 1 DELETE FROM t is refused. For a comment, put a digit after the currency sign ($0 --); for a minus, put a space between the dashes ($- -1). A $ that ends a column name (amount$ -- note) belongs to the name, so the -- after it starts a comment and the query runs. On MySQL, 1.5e-- 1 is a number and a minus sign rather than a comment, so a statement after it is checked too: SELECT 1.5e-- 1; DELETE FROM t is refused. MySQL's SHOW CREATE … stays a read. A column or table whose name is one of these words has to be quoted ([update], "update" or `update`) to run at Read-only; the refusal names the word it found. Dashboard previews and scheduled refreshes use the same check. It reads SQL text only: a write inside a function, view or trigger the query calls is invisible to it, so connect with a read-only database login when writes must be impossible. At Confirm the same check decides which queries ask for your approval.

What Read-only runs although its words are on that list. A few statements are reads all the same. Each is checked by a parser of its own, and anything outside the shape described here is refused:

  • SQL Server system procedures that only read: sp_help, sp_helptext, sp_helpindex, sp_helpconstraint, sp_helptrigger, sp_helpdb, sp_helpfile, sp_helpfilegroup, sp_columns, sp_tables, sp_fkeys, sp_pkeys, sp_statistics, sp_stored_procedures, sp_databases, sp_server_info, sp_who, sp_who2, sp_spaceused, sp_describe_first_result_set and sp_describe_undeclared_parameters, called as EXEC sp_help 'dbo.Orders'. The name must be in lower case and written as sys.sp_… (or database.sys.sp_…), because a dbo. or other schema can hold a user procedure of the same name. sp_help, sp_helptext, sp_helpindex, sp_helpconstraint, sp_helptrigger, sp_columns, sp_tables, sp_fkeys, sp_pkeys, sp_statistics, sp_stored_procedures, sp_server_info and sp_spaceused may also be called bare. The other eight are missing from some SQL Server and Azure SQL editions, and there a bare name can reach a user procedure, so they run only as sys.name (EXEC sys.sp_who2). The arguments must be literals, names or @param = a literal, and nothing may follow them before the next ; or GO. sp_spaceused with @updateusage and sp_statistics with @accuracy are refused, because they write.
  • SQL Server variables: DECLARE of scalar variables with a built-in type, and SET @var = …, whose value is checked like a SELECT. Whatever follows a variable's value is checked as a statement of its own. A table or cursor variable is refused.
  • SQL Server SET NOCOUNT and SET STATISTICS IO / TIME.
  • Oracle SYS.DBMS_METADATA.GET_DDL, GET_DEPENDENT_DDL and GET_GRANTED_DDL, and SYS.DBMS_XPLAN.DISPLAY, DISPLAY_CURSOR and DISPLAY_AWR, written with SYS.: a bare name can reach a package of that name in the current schema. The DBMS_XPLAN readers take literal arguments only (a string, a whole number or NULL), and DISPLAY at most three — never its fourth, filter_preds, which Oracle runs as SQL, so a function named there would be called. Every other DBMS_* call stays refused.

Session settings run only in query_execute. On SQL Server, PostgreSQL, MySQL and Oracle, each query_execute call runs on a pooled connection that is reset or closed afterwards, so a setting cannot reach your later queries. There Read-only also runs USE (SQL Server and MySQL), the other SQL Server SET options (STATISTICS XML / PROFILE, ANSI_NULLS, ANSI_PADDING, ANSI_WARNINGS, ANSI_NULL_DFLT_ON, ANSI_NULL_DFLT_OFF, ARITHABORT, ARITHIGNORE, CONCAT_NULL_YIELDS_NULL, NUMERIC_ROUNDABORT, QUOTED_IDENTIFIER, XACT_ABORT, DATEFORMAT, DATEFIRST, LANGUAGE, LOCK_TIMEOUT, TEXTSIZE), SELECT … INTO #temp (a local temporary table written as a bare #name; #db.dbo.t names a table in a database called #db and is refused), PostgreSQL SET search_path and Oracle ALTER SESSION SET NLS_*. Oracle EXPLAIN PLAN is refused everywhere, query_execute included: it writes the plan into PLAN_TABLE, which can be a permanent table that keeps the rows. Run the query instead, then read its plan with SYS.DBMS_XPLAN.DISPLAY_CURSOR('<sql_id>'), taking the sql_id from v$sql. An estimated plan from query_execute_with_plan uses Oracle's session-private plan table (SYS.PLAN_TABLE$), never a PLAN_TABLE in the schema, and deletes its rows. SQLite runs every call on the connection's one shared handle, so Read-only takes no session setting there; a PRAGMA that sets a value is refused, also after EXPLAIN or EXPLAIN QUERY PLAN. ui_execute_query and the notebook tools refuse session settings: a query tab that holds a transaction, or a notebook, keeps its session for the statements you run next. SET ROWCOUNT, SET TRANSACTION ISOLATION LEVEL, SET ANSI_DEFAULTS and SET IMPLICIT_TRANSACTIONS (the last two open transactions) are refused everywhere. On SQL Server a SET, USE or DECLARE that follows another statement without a ; is checked as the statement it starts, so SELECT 1 SET ROWCOUNT 1 is refused; CLOSE, DEALLOCATE and REVERT are refused too. A USE is a query hint only inside OPTION (…), as in OPTION (USE HINT ('…')); any other USE (SELECT 1 USE hint included) is the statement. A query that holds one of these statements is refused when Read-only cannot read its text with certainty: an unclosed string, comment or quoted name, a non-breaking or zero-width space, a MySQL /*! */ comment, or a backslash in a MySQL or PostgreSQL string.

For the refusals agents meet most, the reply to the agent ends with an Instead: line that names the rewrite: three-part names (SQL Server) or database.table names (MySQL) instead of USE in a query tab, schema-qualified names instead of SET search_path, TO_CHAR / TO_DATE with a format instead of NLS settings, TOP instead of SET ROWCOUNT, or sp_helptext to read a procedure's code instead of running it.

A FROM-first query — FROM t SELECT …, the Fabric Warehouse T-SQL form, also after a WITH list — counts as a read at Read-only, like the SELECT it stands for. Its INTO form (FROM s SELECT a INTO #t) creates a table and is refused like SELECT … INTO. A second statement after it is refused too: any statement after a ; or a GO line, and a write, procedure call or other statement from the list above even with no separator at all.

A few tools execute code rather than a query, so there is nothing for the read-only classifier to approve. Those are judged by level instead, and all of them are refused at Block and Read-only: debug_start (runs a PL/SQL block the agent wrote), plsql_compile / plsql_compile_all / plsql_compile_debug (replace or recompile a stored program), debug_evaluate_expression (evaluating an expression runs code in the session being debugged), and stepping a paused program with debug_step_over / debug_step_into / debug_step_out / debug_continue (resuming it runs whatever it does next).

What they do at Confirm differs, and it is worth knowing which is which:

  • debug_start shows you the exact PL/SQL block in the same blocking dialog a write query gets, every time. There is no "remember" option — a block the agent composed is the most open-ended thing it can ask for, so it never runs on an earlier approval.
  • plsql_compile*, the stepping tools, and the breakpoint tools ask in an in-app card that offers Remember for this session. That grant is scoped to one tab and one kind of action: saying yes to stepping does not also authorise recompiling. The card appears in the AI Chat panel of the tab you are on. When the agent names a tab, it appears only in that tab, and only while that tab is on screen; AI Chat panels in other tabs do not show it. For a package open in Package Explorer, the card appears in the Package Explorer tab’s AI Chat while that package is the one selected. Selecting another package hides the card, and selecting that package again brings it back; the 60 seconds below keep counting while it is hidden. If AI Chat is closed in the tab you are on, or the agent named another tab, nobody can answer it, so the call is refused within about 5 seconds with “the prompt was not shown”, not as a denial. A card you leave unanswered for 60 seconds counts as declined and goes away.
  • debug_evaluate_expression never prompts, because on the agent's side there is nothing to prompt about. It answers with whatever the debugger itself can read out of the paused frame — v_total, l_emp.salary, a variable in scope at the current line, NULL included — and refuses everything else rather than evaluating it. Arithmetic, a function call, a name that is not in scope here: answering any of them would mean running code inside the session you are debugging, in its transaction, and what that code does is not visible in the expression text. No permission level in Jam SQL Studio grants an agent "run arbitrary code", so there would be nothing for you to say yes to. A refusal is not a verdict that what the agent asked for was dangerous — an out-of-scope variable is refused the same way as a function call. Your own watch panel is unaffected — it still evaluates whatever you type, and nothing was added to the checks it shares.

Ending a transaction is likewise a write: transaction_commit makes pending changes permanent and transaction_rollback discards them — including statements you ran in that tab — so both are refused at Read-only and prompt at Confirm. Setting, clearing or toggling a breakpoint runs no code and changes no data, so it is not level-gated; it still asks.

Write Approval Flow (Confirm Mode)

When permission level is set to Confirm, AI agents can execute write queries (INSERT, UPDATE, DELETE, etc.) but only after you approve each one in an in-app dialog:

How It Works

  1. AI agent submits a write query via query_execute (or runs a query tab or notebook cell with ui_execute_query or the notebook tools)
  2. Jam SQL Studio shows an approval dialog, headed with the question (for example Run this DELETE query?, or Run these 3 statements? for a batch) and marked Requested by AI, with:
    • Query type badge (INSERT, UPDATE, DELETE, etc.)
    • The SQL, with its own line breaks, in a scrollable box. A statement longer than 250 characters shows its first 250 characters; Show full SQL shows all of it exactly as it runs and Show less shortens it again. The shortened view starts after any comment the statement begins with and says how many characters of comment it hides (for example Leading comment hidden (512 characters)). SQL that Jam SQL Studio cannot split into statements — a PL/SQL block, COMMIT, or text that ends inside an unclosed string — is shown in full from the start, because a second statement could otherwise sit in the shortened part. So is a statement whose shortened part holds a keyword that can start a write, such as a DELETE after an UPDATE with no semicolon between them on SQL Server, and a statement whose code Jam SQL Studio cannot read word by word: a procedural block (PostgreSQL DO, an Oracle or T-SQL BEGIN … END, with or without a label, and on MariaDB an IF, WHILE, LOOP, REPEAT or CASE block run outside a procedure), a function, procedure or trigger definition, or SQL run from a string (EXEC('…'), sp_executesql, sp_prepexec, OPENQUERY, OPENROWSET and OPENDATASOURCE on SQL Server, EXECUTE IMMEDIATE on Oracle and MariaDB, PREPARE … FROM and EXECUTE on MySQL, the dblink functions and any name written with Unicode escapes, U&"…", on PostgreSQL). When a request contains one of these statements, every statement and notebook cell of the request is shown in full, since the SQL that statement runs can be stored as text in another statement, for example with set_config on PostgreSQL or a DECLARE on SQL Server. For the same reason, a request with more than one statement or notebook cell is shown in full when a text value in quotes runs past the shortened part of its statement, whichever statement might run it (on SQLite a double-quoted value counts, since SQLite can read it as text). A single statement can store a text value and run it too, as in EXEC dbo.run_sql N'…' or SELECT set_config('app.cmd', c, false), run_cmd() FROM (SELECT '…' AS c) x, so it is shown in full when a text value runs past its shortened part, wherever the value sits — unless the statement is an INSERT, UPDATE, DELETE or MERGE (or REPLACE on MySQL and SQLite), also after a WITH list or a label. Those keep the shortened view with long text values, including a value passed to a function, procedure, cast or operator, directly or through a subquery, CTE or VALUES list, which on PostgreSQL or Oracle could run it as SQL. A request with a backslash in a string on PostgreSQL or MySQL, where what the backslash means depends on server settings, is shown in full from the start when any of its statements is longer than 250 characters. A notebook cell's label, such as -- cell 1 of 2 (each runs separately), stays in the shortened view. When a hidden character (a control, zero-width or text-direction character, shown in the full SQL as a marker such as ⟨U+202E⟩) is in the part the shortened view leaves out, the dialog says so
    • For a batch, each statement on its own, marked Write, May write or Read; only each statement's text is shortened, never the list. A procedure, function or trigger definition is one statement with its body: on SQL Server the body runs to the next GO
    • For each UPDATE and DELETE, how many rows it matches right now (see Row counts)
    • Connection and database context
    • Countdown timer showing time left to respond
  3. You choose: Approve to execute, or Deny to block. Deny has the keyboard focus when the dialog opens, and focus returns to where you were when it closes. The dialog fits the window: long SQL scrolls inside it, and the two buttons stay in view
  4. If you don't respond, the query is denied
  5. Result (success/denied) is returned to the AI agent

Write Approval Guardrails

  • Timeout protection: Queries are denied if you don't respond
  • Full audit logging: Every write attempt (approved or declined) is recorded in AI activity with its time and outcome, and its SQL when Include SQL text in audit is on
  • Per-connection override: Set permission level per connection (e.g., read-only on production, confirm on dev)
  • No batch bypass: In Confirm mode a multi-statement query with a write raises the approval dialog with the whole script — batching writes together with reads doesn't skip approval

Row counts

For an UPDATE or DELETE the dialog shows Counting…, then Affects N rows: the number of rows the statement's WHERE clause matches at that moment. Jam SQL Studio counts them with a SELECT COUNT(*) built from the statement's table and WHERE clause, on the same connection and database the write would run in. It never runs the write itself to find out, so no trigger fires and nothing changes. The count is a read like any other an agent may run at Confirm; it stops after 5 seconds, and it is cancelled when you answer before it finishes.

  • Couldn't count: … — the count failed or took too long; the reason follows.
  • Row count not available for this statement — the statement is not a plain single-table UPDATE … SET … WHERE or DELETE FROM … WHERE. Joins, a FROM or USING clause in the statement, OUTPUT / RETURNING, TOP / LIMIT / ORDER BY, a WITH prefix, MERGE, variables and bind parameters (@id, :id, ?, $1), and temporary tables are not counted. Neither is a statement that follows USE, SET search_path, ALTER SESSION, a procedure call, or a statement that creates, drops, renames or empties a table (CREATE TEMP TABLE, SELECT … INTO, DROP, TRUNCATE) in the same batch, because the table name may then point somewhere else. For a query tab with an open transaction, and for a notebook, the count is not taken either: it could not see the changes and settings the tab's own session holds. On SQLite the count runs in a separate process on a read-only connection of its own, so a slow count never stops the app, and answering the dialog ends that process at once, so the write you approve never waits for it. For a SQLite database with attached databases or temporary tables the count is not taken.
  • Not counted — a batch gets at most five counts; later statements are not counted.

In a batch every count is taken before any statement runs, so a count does not include changes the earlier statements would make. The counts work the same on SQL Server, PostgreSQL, MySQL, Oracle and SQLite. Azure Data Explorer (Kusto) and Azure Storage have no SQL UPDATE or DELETE, so their approvals show no count.

Connecting to a saved connection

An agent can ask Jam SQL Studio to connect to one of your saved connections with connections_connect. Jam SQL Studio signs in with the credentials saved for the connection; the agent never sees the password. What happens is set by Settings → AI Integrations → Allow AI to connect using saved connections:

  • Deny: the agent is refused and told which setting you can change.
  • Confirm each (default): a dialog names the connection, with its server and database, and the agent when its client says which one it is, and offers Allow once, Always allow for this connection and Don't allow. Don't allow has the keyboard focus, and Esc answers it. If nobody answers within 60 seconds, the agent is not connected. One dialog is shown at a time, and several requests for the same connection share one dialog. If the agent cancels its request while the dialog is open, the dialog closes (unless another request shares it) and Jam SQL Studio does not connect. If you set the setting to Deny while a dialog is open, Jam SQL Studio does not connect, even if you then choose Allow once or Always allow, and does not store Always allow. If Jam SQL Studio cannot save Always allow, it shows an error, connects this time, and asks again next time. A connection that is already open in Jam SQL Studio and able to run queries is not asked about: the agent is told it is already connected. A SQLite connection whose file could not be closed, or an Oracle connection whose pool has to be rebuilt, is asked about like any other, and Jam SQL Studio reconnects it once you allow it. If you have work open on that connection (an open transaction, a notebook session or a running query), Jam SQL Studio does not reconnect it, so nothing is rolled back; the agent is told to ask you to finish that work and reconnect. A request for a connection Jam SQL Studio cannot find among your saved connections is refused.
  • Allow: the agent connects without asking.

On macOS and Linux, a SQL Server connection saved with Windows authentication cannot connect (see Windows Authentication). The agent gets that reason at once, with a note to ask you to change the connection’s Authentication; no approval dialog is shown and the server is not contacted.

Always allow for this connection connects and stops asking for that connection while the setting is Confirm each. Deny still refuses it. The grant is shown in the connection's settings under More options → AI connect; untick it and save to be asked again. It stays on this computer: exporting connections leaves it out, and changing the connection's engine removes it. The grant and the connection's own AI permission level change only when you edit them in the connection's settings or answer Always allow: a reconnect, setting the default database or another save made in the background keeps the values you set last.

When you choose Don't allow, the agent is told not to ask for that connection again and to ask you to connect in the app if it needs to. Before this release the setting was an on/off switch, off by default: a switch that was on becomes Allow, and one that was off becomes Confirm each.

Time limits and unreachable connections

Time limit. query_execute stops a query that runs past Settings → AI Integrations → Query timeout (30 seconds by default); timeoutSeconds on a call can only lower it. Jam SQL Studio asks the server to cancel the query and tells the agent how long it waited, whose limit that was, and whether the query stopped: Jam says so only when the query itself ended within a few seconds of the cancel, on every engine; otherwise the agent is told it may still be running there. For a read, the reply suggests a cheaper query in the connection's own syntax: a row limit, filters on indexed columns, or an estimated plan to find the slow step. It also suggests opening the query in a query tab for you to run: query tabs use the app's own query timeout (Settings → Advanced, 300 seconds by default), not the agent limit. The scripts that blueprint_apply_schema and blueprint_sync_data run follow the same limit.

Dropped connection. When the server closes the connection while a query runs, query_execute does not run it again, because Jam SQL Studio cannot tell whether the statement completed on the server. The agent is told so, that the next call reconnects, and to run the query again only if repeating it is safe: for a write, or a function that may change data, it first checks whether it took effect. A connection you disconnected in the app is not reconnected by an agent's query.

Unreachable server. When a connection fails to connect — the server refuses the connection, the host name is not found, a firewall or SSH tunnel blocks it, or the server rejects the login or the encryption settings — the tools that would reach that server answer the agent at once for about a minute instead of dialling it again. The answer says what failed, when, and after how many attempts, and asks the agent to tell you rather than retry. Connecting or reconnecting in the app, an agent's connections_connect, or saving the connection's settings lets calls through again. ui_open_tab and reading MetaInfo are not held back, and neither are SQLite connections, which have no server. An error from a statement on a working connection, such as a missing role or a database link or linked server whose login fails, never does this. Apart from an agent's own connections_connect, only a failure to reach the server (refused, host name not found, no route) does, an encryption failure Jam SQL Studio's own connection attempt reported (such as an untrusted or expired certificate, or encryption the server does not offer), or a login refused while Jam SQL Studio itself was connecting (on SQL Server, PostgreSQL, MySQL and Oracle; for Azure Data Explorer and Azure Storage, a sign-in Microsoft Entra refused). A call the tool would refuse anyway, such as a query at permission level Block, a write at Read-only (a storage write included) or a query on an Azure Storage connection, gets that refusal instead.

Agent Capabilities

Some MCP tools are controlled by additional toggles in Settings → AI Integrations:

  • Allow AI to connect using saved connections — Deny, Confirm each or Allow; Confirm each by default (see Connecting to a saved connection)
  • Allow AI screenshots — On by default (disable if you handle sensitive data)

AI activity: what agents did

AI activity lists every tool call AI agents made through the MCP server, newest first, and adds new calls while it is open. Open it from the AI menu, the command palette (AI Activity), or Settings → AI Integrations → Audit & Logging → View AI activity.

  • Columns — time, the AI tool (Claude Desktop, Claude Code, Cursor, VS Code, Codex, Windsurf, Zed, the jam-sql CLI, or Other), the tool it called, the connection and database, the outcome, the rows it got back and how long the call took.
  • Outcomes — Ran; Approved (you approved it in Jam and it ran); Declined (you declined the approval, closed it, or let it expire); Denied (the permission level or a setting refused it); Error. Click a row to see why it was refused, the error, and the SQL.
  • SQL text is recorded only while Include SQL text in audit is on. With it off, the history keeps the tool, connection and outcome without the query.
  • Errors — the error message is recorded only while Include SQL text in audit is on, because database errors can quote the SQL and row values. With it off, a failed call keeps the kind of error (for example A constraint refused the change) and the driver's error code, such as 23505 or ORA-00942.
  • Filters — by connection (including calls that named none) and by outcome. Clear history deletes every recorded call after a confirmation.
  • Where it is kept — in a file in Jam's data folder on this computer: calls from the last 30 days, at most 20,000 calls and 20 MB. When the file reaches either limit, Jam drops the oldest calls. Nothing is recorded while Audit AI tool calls is off.
  • Agents cannot read it: no MCP tool or resource returns the history. It is for you, to check what an agent did.

jam-sql CLI

Jam SQL Studio ships with a CLI tool (jam-sql) that wraps the MCP server for terminal access. The CLI is bundled with the app and automatically installed to your PATH on every launch — always in sync with your app version.

The CLI is also used by the Jam SQL AI Skill. Run jam-sql add-skill to install the skill for Claude Code, Cursor, Copilot, Codex, Windsurf, and 20+ other AI agents — the skill teaches your agent how to use the CLI to interact with your databases.

Pairing

Run jam-sql pair to securely connect the CLI to a running Jam SQL Studio instance. No manual token copying — the CLI obtains the token directly from the app using a challenge-response protocol:

# Pair with the running app (one-time setup)
jam-sql pair

# A verification code is displayed — confirm it matches
# the dialog shown in Jam SQL Studio, then approve.

How pairing works

  1. The CLI reads ~/.jamsql/mcp-discovery.json (written by the running app) to find the MCP server port
  2. Sends a pairing request to the app — the app generates a short verification code (e.g., JAZZ-7742)
  3. The code is displayed in both the terminal and a consent dialog in Jam SQL Studio
  4. You verify the codes match and click Approve in the app
  5. The CLI receives the MCP bearer token and stores it in ~/.jamsql/credentials with 0600 permissions (owner-read only)

After pairing, all CLI commands automatically resolve the endpoint and token. No environment variables, no flags, no config files.

Security model

  • Rogue pairing request — user must verify the code in the app UI matches the terminal. A remote attacker cannot see the code displayed on your screen.
  • Token interception — all MCP traffic is over localhost loopback (127.0.0.1). The token never leaves the machine, and the endpoint is not routable from the network.
  • Token on disk — ~/.jamsql/credentials has 0600 permissions (owner-read only), stored in the user's home directory, never in a project directory, never committed to git.
  • Brute-force pairing — rate limited: max 3 concurrent sessions, 10 requests/minute, 2-second poll interval, 120-second expiry.
  • Stale discovery — CLI checks PID liveness before trusting the discovery file. Stale entries from crashed processes are detected.
  • Port scanning — discovery file replaces port scanning. CLI reads the exact port from ~/.jamsql/mcp-discovery.json.
  • Unauthorized MCP access — all MCP endpoints (except /status and /pair/*) require a valid Bearer token. Pairing endpoints are origin-validated and rate-limited.

Commands

After pairing, all commands work without manual token or endpoint configuration:

# Check installation and pairing status
jam-sql doctor

# Show pairing + app status
jam-sql status

# Launch the app if not running
jam-sql launch

# List saved connections
jam-sql connections

# Execute a query
jam-sql query -c production "SELECT * FROM users LIMIT 5"

# List available MCP tools and resources
jam-sql tools
jam-sql resources

# Call any MCP tool directly
jam-sql call ui_open_tab '{"type": "query"}'

# Browse an Azure Storage connection
jam-sql storage containers -c storage-account
jam-sql storage ls -c storage-account images/2026/09/
jam-sql storage download -c storage-account images/2026/09/photo-00001.png

# Read an MCP resource
jam-sql read sql-studio://context/tabs

# Remove stored credentials
jam-sql unpair

jam-sql query takes --max-rows and --timeout (in seconds) to ask for fewer rows or a shorter time limit than Settings → AI Integrations allows; a larger value gets the Settings value. Without --timeout, the agent query timeout from Settings applies, and the CLI waits as long as the app takes. With --timeout, the CLI stops waiting after that many seconds plus two minutes (time for a write’s approval prompt) and asks the app to cancel the query. The query may still finish, so check whether a write took effect before running it again.

MCP Apps: results as views in Claude Desktop

In an AI app that supports MCP Apps, some Jam SQL Studio tools show their result as a small view in the conversation instead of JSON text: a sortable grid for query results, a column list for a table, a graph for dependencies. The view shows the same data the agent received for that tool call, and nothing else.

ToolViewWhat it showsOpen in Jam SQL Studio
query_executeQuery resultsThe SQL with highlighting and every result set, 25 rows per page, sortable by column; NULLs marked; a note when the row limit cut the resultOpens the SQL in a new query tab on the same connection and database (it does not run it)
table_get_snapshotTable dataThe preview rows of the Table Explorer tab the agent read, with column types, PK / FK marks, a filter box and sortingBrings that tab to the front
schema_get_columnsTable schemaEach column with its position, type and size, nullability, default, and PK / identity marksOpens the table or view in Table Explorer
schema_get_dependenciesDependency graphThe object in the middle, what it uses and what uses it, with zoom and pan, and the same objects as two listsOpens a table or view in Table Explorer
schema_compare_generate_script, data_compare_generate_scriptSync scriptThe generated script with highlighting, its statement counts and warningsOpens the script in a new query tab (not offered when the agent got a cut-down script)

Which AI apps show the views

  • Claude Desktop shows them for Jam SQL Studio once it is connected through npx -y @jamsql/mcp. The first time, Claude asks whether to display the app: choose Allow, or Always allow.
  • Claude Code and other clients that do not render MCP Apps get the same tool result as text, exactly as before.
  • claude.ai in the browser and the mobile apps cannot reach the MCP server on your computer, so they do not show these views.
  • Any other AI app that implements the MCP Apps extension can render the views the same way.

There is nothing to turn on in Jam SQL Studio: with the MCP server enabled, the tools above carry their view. Permission levels apply as usual; when a call is refused or fails, the view shows the reason instead of data.

The Open in Jam SQL Studio button

Each view has a small Jam SQL Studio footer and an Open in Jam SQL Studio button. The button asks the AI app to call one of Jam SQL Studio’s UI tools (ui_open_tab or ui_focus_tab), so the AI app may ask you before it runs, and the connection’s permission level still applies: at Block, a Table Explorer tab is refused and the footer says why. No view has a button that runs SQL or approves anything; a write still waits for your answer in Jam SQL Studio’s own window (see Permission Levels).

Privacy: what the views load and send

  • The view is an HTML page that Jam SQL Studio serves to the AI app as an MCP resource (ui://jam-sql/…). It holds no data of its own. The AI app runs it in a sandboxed frame inside its window.
  • The page receives the tool call’s arguments and result from the AI app, which already has them because the agent made the call. It shows only that.
  • It loads nothing from the internet: all of its code is inside the page, and its Content Security Policy blocks every network request, image, font and frame.
  • With Usage Analytics on (Settings → Privacy), Jam SQL Studio counts which views AI apps read: the view name only, never any data.
A view that stays empty

When Claude’s code execution is on and a tool result is larger than about 150,000 characters, Claude Desktop keeps the result out of the conversation and the view has nothing to show. Ask for fewer rows, or lower the row limit in Settings → AI Integrations.

Which Approach Should You Use?

All approaches complement each other:

  • Use AI Chat Sidebar for quick, conversational assistance while writing queries or building notebooks. It's the fastest way to get AI help without leaving your editor.
  • Use AI Workspace when you want to iterate on queries with AI agents using the integrated terminal + file sync workflow.
  • Use the Jam SQL Skill + MCP Server when you're working in an external AI tool (Claude Code, Cursor, Copilot, Codex, etc.) and need your agent to understand Jam SQL Studio and access your databases. Install the skill with jam-sql add-skill, then enable the MCP server for live database access.
  • Use all three for maximum flexibility — the sidebar for quick help, AI Workspace for file-backed collaboration, skill + MCP for external tool integration.

Ready to Work with AI?

Download Jam SQL Studio and experience AI-native database tooling.

Frequently asked questions

What is the difference between AI Chat Sidebar, AI Workspace, and MCP Server?

AI Chat Sidebar is a built-in chat panel in the Query Editor and SQL Notebooks powered by your locally installed Claude CLI or Codex CLI — no extra subscription required. AI Workspace runs inside Jam SQL Studio with an integrated terminal for AI agents to edit .sql files directly. MCP Server exposes your databases to external AI tools like Claude Desktop or Codex CLI via the Model Context Protocol.

How do I connect Claude Desktop to Jam SQL Studio?

Add a jam-sql entry to claude_desktop_config.json that runs npx -y @jamsql/mcp. The @jamsql/mcp package connects Claude Desktop, which only starts stdio servers, to the local MCP server in Jam SQL Studio. It finds the running app and the token saved by jam-sql pair on its own and runs on Node.js 18 or newer. Enable MCP Server in Settings > AI Integrations and run jam-sql pair once first. See the documentation for the full setup.

Is the MCP connection secure?

Yes. The MCP server binds to localhost only (127.0.0.1) and requires bearer token authentication. It executes no queries by default — you can allow read-only (SELECT-class) queries, or enable Confirm mode, where each write or DDL statement runs only after you approve it in an in-app dialog. Passwords are never exposed and all tool calls are logged.

What AI tools work with Jam SQL Studio's MCP Server?

Any MCP-compatible tool works: Claude Desktop, Claude Code, Codex CLI, OpenCode, GitHub Copilot (via MCP extension), and custom agents built with LangChain, AutoGen, or any HTTP client.

Can AI tools modify my database through MCP?

Only if you explicitly enable Confirm mode and approve each write query in-app. No queries run by default; the Read-only permission level (an opt-in step up from the block default) restricts MCP to reads such as SELECT, EXPLAIN, SHOW, PRAGMA and SQL Server’s read-only system procedures.

What do I need to use the AI Chat Sidebar?

Just install Claude Code CLI or Codex CLI (or both). Jam SQL Studio uses your existing CLI installation — no additional subscription or API key configuration in Jam SQL is required.

Which AI backends does the AI Chat Sidebar support?

Claude CLI and Codex CLI. Install either or both — Jam SQL auto-detects available CLIs and lets you switch between them.