Last updated: 2026-08-10

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.

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.

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.

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.

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
• 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.

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 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.

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.

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

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.

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) 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 SQL 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.

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.

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 — Requires mcp-remote proxy and Node.js 20+ (see setup guide above)
• 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)

Manual MCP Setup (per-tool configuration)

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

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

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

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

claude mcp list

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

export JAM_SQL_MCP_TOKEN="YOUR_TOKEN_HERE"

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

node --version  # Must be v20.0.0 or higher

{
  "mcpServers": {
    "jam-sql": {
      "command": "/path/to/node20+/bin/npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:14507/mcp",
        "--header",
        "Authorization:${JAM_SQL_TOKEN}"
      ],
      "env": {
        "JAM_SQL_TOKEN": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

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}'

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

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 — 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.

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.

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.
• 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:

Agent Capabilities

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

• Allow AI to connect using saved connections — Off by default (uses saved credentials)
• Allow AI screenshots — On by default (disable if you handle sensitive data)

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 communication is over localhost loopback (127.0.0.1). Never leaves the machine, 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"}'

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

# Remove stored credentials
jam-sql unpair

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.

Frequently asked questions