Model Context Protocol (MCP)

Model Context Protocol (MCP) lets AI tools query your databases through DBCode. The AI can list connections, read schemas, and run queries on your behalf.

The MCP server is free for everyone.

In VS Code and Cursor, DBCode registers itself with the editor’s MCP host automatically. There is nothing to configure: install DBCode and the tools appear in the chat picker. In Antigravity, Windsurf, and Kiro, setup is one click: DBCode offers to add itself to your editor’s MCP configuration the first time it loads. Agents outside the editor, such as Claude Code or Claude Desktop, use the DBCode CLI: install it once and add dbcode mcp to the client.

VS Code & Cursor (auto-registered)

When DBCode loads in VS Code or Cursor, it registers itself with the editor’s MCP host. No mcp.json to edit. No port to configure. Each editor window connects independently.

VS Code

1. Install DBCode.
2. Open Copilot Chat in agent mode.
3. Click the tools icon at the bottom of the chat input: DBCode appears as a server with its tools listed underneath.
4. Ask Copilot to do something with your data (“list my dbcode connections”, “show me the schema for orders in my postgres database”). You’ll be asked to sign in to DBCode the first time, if you aren’t already.

You can also confirm registration via the command palette: run MCP: List Servers and look for DBCode.

Cursor

1. Install DBCode.
2. Open Cursor’s MCP settings or tools picker: DBCode is listed automatically.
3. Use a chat that allows MCP tools and ask a database question. First use triggers a DBCode sign-in if needed.

You don’t need to add anything to .cursor/mcp.json for DBCode. Cursor discovers the server through DBCode’s extension registration.

Antigravity, Windsurf & Kiro (one click)

These editors read MCP servers from their own configuration file rather than the VS Code MCP API. The first time DBCode loads, it asks:

Let Antigravity’s AI agent query your databases through DBCode?

Choose Enable and DBCode adds itself to the editor’s MCP configuration - existing servers in the file are untouched. Reload the agent (or the window) and DBCode appears in the agent’s MCP server list, ready to answer database questions.

If you dismissed the prompt, or removed the entry and want it back, run DBCode: Enable AI Tools in This Editor from the command palette.

Each editor window advertises itself to the agent automatically; whichever DBCode window is most recently active serves the agent’s requests.

Other editors

If your editor is not one of the above, install the CLI and add dbcode mcp to its MCP configuration, the same way as for an external agent.

Scoping what an agent can do

An agent’s access is as narrow as you decide. The connection-level guardrails are free:

• The connection’s role and read-only mode set what any client can reach.
• Missing WHERE detection catches a destructive query whether a human or an agent wrote it.

For a tighter, AI-specific limit, AI access roles give an agent its own role that can only narrow what you can do, never widen it. Assigning one needs DBCode Pro; the default, Same as user, is free.

External agents

Agents that run outside the editor, such as Claude Desktop, Claude Code, GitHub Copilot CLI and Codex, get DBCode through the CLI. Run DBCode: Install CLI from the command palette once, then add dbcode mcp to the client:

{
  "mcpServers": {
    "dbcode": { "command": "dbcode", "args": ["mcp"] }
  }
}

The client starts it and stops it. It serves the same tools from your saved connections, under the same roles, licence and masking rules. No port, no sign-in, no server to start. If more than one editor on the machine has DBCode connections, add "--app", "Code" (or Cursor, Windsurf, and so on) to the arguments. What happens with and without a running editor: MCP without the editor.

Claude Desktop

Add the entry above to claude_desktop_config.json: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%/Claude/claude_desktop_config.json on Windows. Restart Claude Desktop.

Claude Code

claude mcp add dbcode -- dbcode mcp

This writes the local scope (the current project). Use --scope user for every project on the machine, or --scope project to check the entry into .mcp.json for teammates. claude mcp list confirms it; /mcp inside a session shows the tools.

GitHub Copilot CLI

Run /mcp add in a Copilot CLI session: server name dbcode, server type Local, command dbcode, arguments mcp, tools *. Or edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "dbcode": {
      "type": "local",
      "command": "dbcode",
      "args": ["mcp"],
      "tools": ["*"]
    }
  }
}

/mcp show dbcode lists the tools.

Codex CLI

codex mcp add dbcode -- dbcode mcp

HTTP server

DBCode also has a localhost HTTP MCP server. It is off by default and is the right choice when:

• You want the agent’s session inside the running editor, with the editor’s approval prompts and activity view.
• The agent runs in a Dev Container or on another machine, where the CLI cannot see your connections.
• The client speaks HTTP only.

The quick way: Connect an AI Agent

Run DBCode: Connect an AI Agent from the command palette. It starts the server if needed and copies ready-to-paste setup for your agent: a claude mcp add or codex mcp add command, or a JSON server entry for any other client.

Settings

Open DBCode MCP Settings and review:

• dbcode.ai.mcp.autoStart (MCP HTTP Server Auto Start): start the server every time DBCode loads.
• dbcode.ai.mcp.port (MCP HTTP Server Port): default 5002.
• dbcode.ai.mcp.authorization (MCP HTTP Server Authorization): OAuth (default) or None.
• dbcode.ai.mcp.allowExternalConnections (MCP HTTP Server Allow External Connections): needed for Dev Containers and LAN access. Keep OAuth on so those connections are authenticated.

These settings affect only the HTTP server, not the auto-registered path or the CLI.

Start and stop

Run DBCode: MCP Start HTTP Server from the command palette. The server listens on http://localhost:5002/mcp; in OAuth mode the discovery endpoint http://localhost:5002/.well-known/oauth-authorization-server is available too. DBCode: MCP Stop HTTP Server stops it.

Point any client at http://localhost:5002/mcp with HTTP transport. For Claude Code:

claude mcp add --transport http dbcode http://localhost:5002/mcp

VS Code and Cursor register DBCode automatically; if you ever configure them by hand, use this URL in their mcp.json.

Authentication

OAuth (default): clients discover the authorization and token endpoints and complete a standard Authorization Code + PKCE flow. On first connection the editor shows an approval dialog (client ID, redirect URI, scopes); approving mints an access token the client reuses. Most modern MCP clients handle this automatically.

None: every request to /mcp is accepted without credentials. Only for local development or trusted environments. Combined with allowExternalConnections it exposes the server to your whole network with no access control.

Dev Containers and LAN

By default the server accepts connections from the same machine only. Enable dbcode.ai.mcp.allowExternalConnections to bind to all interfaces, and keep OAuth on.

From a Dev Container, point the client at the host:

{
  "mcpServers": {
    "dbcode": { "url": "http://host.docker.internal:5002/mcp" }
  }
}

One host server can serve several Dev Containers. From other machines on your network, use the host’s IP address and allow the port through your firewall.

If a stdio-only client must reach the HTTP server, npx -y mcp-remote http://localhost:5002/mcp bridges the two and handles OAuth.

Working with database schema

When using DBCode through MCP, the AI doesn’t automatically know your database structure. You need to explicitly ask it to read your schema before writing queries.

Understanding the workflow

DBCode provides tools that allow the AI to:

• List available database connections (dbcode-get-connections)
• Retrieve databases from a connection (dbcode-get-databases)
• Read complete table schemas including columns, keys, and indexes (dbcode-get-tables)
• Execute queries with the proper context (dbcode-execute-query, dbcode-execute-dml, dbcode-execute-ddl)
• Disconnect to release file locks for file-based databases (dbcode-disconnect)

The AI uses these tools when you ask it to, but you need to guide it through the process.

Prompting best practices

Instead of this (will likely fail or guess incorrectly):

"Show me all records created last month"

Use this (provides proper context):

"First, read the tables and columns from my_database on my PostgreSQL connection.
Then show me all records created last month."

Example prompts

Schema exploration:

• “What database connections do I have available?”
• “List all tables in the production database on my PostgreSQL connection”
• “Show me the complete schema for a specific table, including all columns and foreign keys”

Queries with context:

• “Read the schema from my database, then find all records created in the last 30 days”
• “First get the table structure from analytics_db, then calculate totals grouped by category”
• “What tables exist in my database? After showing me, write a query to find active items”
• “Get the schema first, then show me the top performing entries by metric”

Multi-step workflows:

• “Connect to my MySQL database, read the schema, and then show me how the main tables are related”
• “List my connections, then for the PostgreSQL one, read all tables and identify which contain timestamps”
• “Find my database connections, pick the production one, read its schema, then analyze the data structure”

By explicitly asking the AI to read your schema first, you ensure it generates queries using your actual table and column names rather than making assumptions.

Native query languages

The execute tools aren’t SQL-only. On a MongoDB connection they accept native declarative MongoDB syntax, so an agent can send the same statement you would type in the editor:

db.users.find({ age: { $gt: 21 } }).sort({ age: -1 }).limit(5)

db.orders.aggregate([
  { $match: { status: 'shipped' } },
  { $group: { _id: '$customerId', total: { $sum: '$amount' } } },
  { $sort: { total: -1 } },
  { $limit: 10 }
])

Reads cover find, findOne, countDocuments, estimatedDocumentCount, distinct, and aggregate, with sort, limit, skip, project, and count chained onto a find. Writes cover insertOne, insertMany, updateOne, updateMany, replaceOne, deleteOne, and deleteMany. SQL is still accepted as well, with SELECT, INSERT, UPDATE, and DELETE translated into the equivalent native operations. See Query with SQL for what the translation covers. An agent can use whichever fits the question.

Typed values use the standard constructors, so nothing has to be worked around to reach a BSON type:

db.events.find({
  _id: ObjectId('66a1f2c3d4e5f60718293a4b'),
  createdAt: { $gte: ISODate('2026-01-01T00:00:00Z') },
  sequence: { $lt: Long('9007199254740993') },
  amount: { $gt: Decimal128('19.99') },
  sessionId: UUID('3f2504e0-4f89-11d3-9a0c-0305e82c3301')
})

Date, NumberLong, NumberInt, NumberDecimal, Timestamp, and BinData are accepted too. Every value is validated before it is sent, so a malformed ObjectId or an out-of-range Long comes back as an error rather than a wrong result.

Imperative JavaScript is not accepted from AI tools. Variables, loops, and function definitions are rejected instead of run, and the call is refused before anything reaches the database, which keeps an agent to one reviewable operation at a time. The editor’s MongoDB shell still runs the full scripting language when you need it.

Native syntax changes none of the safety rules. A native write is classified as an insert, update, or delete like any other statement, so your connection’s role still allows, asks, or denies it, and an updateMany or deleteMany with an empty filter trips Missing WHERE detection exactly as a WHERE-less SQL statement does.

Copying data between connections

The dbcode-copy-data tool copies query results from one connection into a table on another connection. The headline use case is pulling rows from a production database into a development or staging database for testing.

The destination table must already exist. If it doesn’t, ask the AI to create it first with dbcode-execute-ddl. Column aliases in the source query define the destination column mapping: DBCode first tries an exact name match, then a case-insensitive match. Aliasing source columns to match destination column names is the recommended way to control mapping.

Parameter	Type	Required	Description
sourceConnectionId, sourceConnectionName	string	Yes	The connection to read from (both the id and name, as returned by dbcode-get-connections).
sourceDatabase	string	Yes	The database to read from.
query	string	Yes	The SELECT statement whose results are copied. Column aliases become the destination column names.
destConnectionId, destConnectionName	string	Yes	The connection to write to.
destDatabase	string	Yes	The destination database.
destSchema	string	No	The destination schema, for databases that support schemas. Defaults to the connection’s default schema.
destTable	string	Yes	The destination table name.
duplicates	error | skip | replace	No	How to handle rows that conflict with existing data. Default: error.
onError	halt | continue	No	Whether to stop or skip bad rows when an insert fails. Default: halt.

Duplicate handling

• error - the operation stops on the first key conflict (default).
• skip - conflicting rows are ignored and the copy continues. On MySQL, INSERT IGNORE is used internally, which suppresses errors beyond key conflicts (such as invalid values); test on a sample first.
• replace - conflicting rows are overwritten. Requires a primary key on the destination table.

Row limit and large datasets

The tool is capped at 1,000,000 source rows per call. For larger datasets, narrow the source query into key ranges and call the tool repeatedly with duplicates=skip - skipping duplicates makes re-runs safe to resume from where a previous call left off.

Progress

If the MCP client sends a progressToken, the tool streams incremental progress as batches are inserted.

Return value

The tool returns a status summary: rows read, rows written, rows failed, duration, and a capped sample of error messages. It never returns the copied rows themselves.

Privacy and security

MCP shares information with connected AI clients only when explicitly requested through MCP tools:

• Database schema (table/column names) when the AI asks about database structure.
• Actual data values when the AI executes queries and returns results.

Important: Unlike inline completion (which only sends schema), MCP tools can read and share actual data from your database when the AI executes queries. Only use MCP with databases containing data you’re comfortable sharing with your AI client.

In VS Code and Cursor, you’ll be prompted to sign in to DBCode the first time you use an MCP tool. The HTTP server has its own authorization (OAuth by default: your editor shows an approval dialog the first time each client connects).

If you’re on a shared multi-user Windows machine (RDS, Citrix, classroom), prefer the HTTP server with OAuth over the auto-registered path.

Privacy guarantees depend on the AI client you connect (Cursor, Claude Desktop, Copilot CLI, etc.). Each client handles data according to its own privacy policy.

See AI Privacy and Security for detailed information on what data is shared, authentication, and security considerations.