Last updated: 2026-02-12

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.

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

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

How to Use AI Workspace

1. Open Jam SQL Studio and go to Settings → AI Workspace
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

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.

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)

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.