MCP & AI database access
Connect Copilot Agent, Cursor, and chat to your saved SQLLens profiles. Agents can discover schema, run read-only queries, and — when you allow it — apply controlled writes — without exposing passwords or manual MCP wiring inside the editor.
What it is
SQLLens registers as an MCP server (Model Context Protocol) named SQLLens. When enabled, AI clients in VS Code or Cursor can use your saved connection profiles on this machine to:
- List connections — profile names, engine type, and identifiers (never passwords).
- Explore databases and schema — databases, schemas, tables, columns, and indexes.
- Run SELECT queries — read-only by default.
- Optionally write — INSERT, UPDATE, DELETE, DDL, or copy-data when you turn off read-only mode and enable writes in Settings.
This is separate from inline SQL generation (LLMs & AI): MCP gives agents structured tools to inspect and query live databases through SQLLens, similar to how DBCode exposes database context to an agent.
VS Code & Cursor
When SQLLens is installed and MCP is enabled, the extension auto-registers the SQLLens MCP server with the editor. You do not need to edit mcp.json for in-editor Agent or chat use.
| Where | What you see |
|---|---|
| Copilot Agent / Cursor Agent | Enable SQLLens in the tools or MCP picker, then ask natural-language questions about your data. |
| Extension Host | SQLLens must be running — use an installed build or Run Extension (F5) during development. |
| First use | A one-time consent modal explains what agents can access; choose Allow to register tools. |
Both the Marketplace extension and a debug (F5) session register MCP. Saved connections are the same profiles you use in the SQLLens sidebar — save at least one before asking agents to query.
@sql and @sqllens chat
SQLLens also registers two chat participants in supported editors:
| Mention | Name | Purpose |
|---|---|---|
@sql | sql | Database assistant backed by the same MCP tools. |
@sqllens | SQLLens | Same behavior — use whichever mention your editor suggests. |
Open chat, type @sql or @sqllens, then:
- Slash commands —
/connections,/databases,/schema,/connect,/disconnect. - Natural phrases — e.g. list connections, show schema, list tables.
- SQL in a fenced block — paste or type
```sql…```; SELECT runs read-only; DML/DDL follow the same safety rules as Agent tools.
Example:
@sql list connections
@sqllens /schema
@sql run this query:
```sql
SELECT region, COUNT(*) AS n
FROM customers
GROUP BY region
ORDER BY n DESC
LIMIT 10
```When an SQL editor tab has an Active database (see per-file database context), chat uses that connection by default.
Agent mode (natural language)
For multi-step questions, use Agent mode (Copilot Agent in VS Code, Agent in Cursor):
- Ensure SQLLens is running and you accepted the first-time MCP consent.
- Open the agent tools picker and enable SQLLens.
- Ask in plain language — the agent chains tools (connections → schema → query) without you writing SQL first.
Example prompts:
- “What tables are in my active database?”
- “How many orders were placed last month on the staging connection?”
- “Show the top 5 slowest-looking tables by row count on the analytics SQLite file.”
The agent picks the right tool calls; you review results in the chat thread. For a single known query, @sql with a SQL block is often faster.
Connection scope
MCP and chat work against all saved profiles in SQLLens — not only the sidebar Active badge.
| Concept | Behavior |
|---|---|
| Default context | When you do not name a connection, tools use the active SQL tab binding or last-used tree context — same rules as Run SQL. |
| Any saved profile | Agents can list every saved connection and target a specific one by name or id when you ask. |
| One operation | Each tool call uses one connection and one database or schema. |
| Engines | MySQL, MariaDB, PostgreSQL, and SQLite profiles are all listed; engine type is included in connection metadata. |
To align chat with a tab, set Active on the database in the connection tree or use /connect after naming the profile.
SQLite profiles
Each SQLite saved profile points at one database file. Agents are not limited to whichever SQLite file is active in the editor — name the profile (for example “ecommerce sample”) and the agent can query that file even when another tab is focused.
Use /disconnect or agent disconnect tools when you need to release file locks before external tools touch the same .db file.
Safety & privacy
Defaults are conservative:
| Setting | Default | Effect |
|---|---|---|
sqllens.ai.mcp.enabled | on | Register SQLLens with MCP clients. |
sqllens.ai.mcp.readOnly | on | Only SELECT-style reads through query tools. |
sqllens.ai.mcp.allowWrites | off | DML, DDL, and copy-data require read-only off and this on. |
- Passwords never leave SQLLens — connection tools return names and metadata only.
- Write consent — chat shows a confirmation modal before DML/DDL when writes are allowed.
- Disable anytime — turn off
sqllens.ai.mcp.enabledto unregister tools, or set read-only to block mutations.
Search Settings for sqllens.ai MCP to adjust all keys. Only enable writes if you trust every agent and client that can reach these tools.
What agents can do (tool summary)
Agents and chat map to a small set of database tools:
| Capability | Typical use | Writes |
|---|---|---|
| List connections | Discover saved profiles and default context | — |
| List databases / schemas | Pick a catalog after choosing a connection | — |
| Table & column metadata | Schema discovery before querying | — |
| Execute query | SELECT (and read-only introspection) | Read |
| Execute DML | INSERT, UPDATE, DELETE | Requires write settings |
| Execute DDL | CREATE, ALTER, DROP, TRUNCATE | Requires write settings |
| Copy data | SELECT → insert into another table (row cap applies) | Requires write settings |
| Connect / disconnect | Open or release pooled connections | — |
External MCP listener (optional)
Inside VS Code or Cursor, MCP uses the built-in registration — no extra listener. For external clients (for example Claude Desktop on the same machine), you can start an optional local listener:
- Run the command SQLLens: Start external MCP listener from the Command Palette.
- Point your external MCP client at the local listener (default port 5012 on this machine).
- Stop with SQLLens: Stop external MCP listener when finished.
Default bind is localhost only. Optional Settings control auto-start on launch, port, bearer authorization, and whether other machines on your network may connect. Keep localhost-only unless you understand the exposure.
The extension must stay running while an external client connects — same as for in-editor MCP.
Getting started
- Install SQLLens from the Marketplace (or F5 from source).
- Save a connection — Connect a database and store at least one profile.
- Open an SQL file (optional) and set Active on the database you want as default.
- First MCP use — enable Agent tools or
@sql; accept the consent modal. - Try a prompt — “@sql list connections” or Agent: “What tables exist in my active database?”
- Tune safety — leave read-only on until you explicitly need agent-driven writes.
Related: LLMs & AI for editor CodeLens and assist panel; Explorer & active database for how Active context is chosen.
Tips & limits
- Name connections clearly — agents match natural language to profile names.
- Specify the database when a connection has many catalogs; default comes from Active context.
- Large results — agents may truncate wide result sets; narrow SELECT lists when possible.
- Cloud sign-in — installed builds may prompt for sqllens.ai sign-in before MCP tools activate; F5 development typically skips this for local connections.
- Turn off MCP — set
sqllens.ai.mcp.enabledto false if you do not want any agent database access.