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.

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.

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.

Other editors

If your editor doesn’t support the MCP extension API, DBCode skips auto-registration silently. You can use the HTTP server approach below, or upgrade your editor.

External clients (HTTP server)

DBCode also ships a localhost HTTP MCP server. Use it when:

• Connecting from Claude Desktop, GitHub Copilot CLI, or another MCP client that isn’t a VS Code-family editor.
• Running DBCode on your host machine while AI clients run in Dev Containers or on other machines on your LAN.
• Using an editor that doesn’t support automatic MCP registration.

The HTTP server is off by default — it’s a separate path from the auto-registered bridge above. Enable it explicitly when you need it.

Settings

Open DBCode MCP Settings and review:

• dbcode.ai.mcp.autoStart (MCP HTTP Server Auto Start) — start the HTTP 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, recommended) or None.
• dbcode.ai.mcp.allowExternalConnections (MCP HTTP Server Allow External Connections) — required for Dev Containers / LAN access. Forces OAuth.

These settings only affect the HTTP server. The auto-registered stdio path used by VS Code and Cursor is unaffected.

Start the HTTP server

Open the command palette (F1 or Cmd/Ctrl+Shift+P) and run:

DBCode: MCP Start HTTP Server

The server listens on:

http://localhost:5002/mcp

In OAuth mode the discovery endpoint is also available:

http://localhost:5002/.well-known/oauth-authorization-server

To stop it, run DBCode: MCP Stop HTTP Server.

Authentication

OAuth (default, recommended)

Clients discover the authorization and token endpoints via /.well-known/oauth-authorization-server and complete a standard Authorization Code + PKCE flow. On first connection VS Code shows an approval dialog (client ID, redirect URI, requested scopes). Approving mints an access token the client reuses for subsequent requests. Denying aborts the handshake.

Most modern MCP clients handle OAuth automatically. Configure the endpoint as http://localhost:5002/mcp with HTTP transport and you’re done.

None

All requests to /mcp are accepted without credentials. Only suitable for local development or trusted environments. Don’t combine None with allowExternalConnections — DBCode refuses and falls back to localhost.

External connections (Dev Containers, LAN)

By default the HTTP server only accepts connections from the same machine (localhost). To expose it beyond that, enable dbcode.ai.mcp.allowExternalConnections. This requires OAuth authorization.

Dev Containers

Run DBCode in a VS Code window on your host. From inside a Dev Container, point the MCP client at host.docker.internal:

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

One host server can serve multiple Dev Containers without running a DBCode instance inside each one.

LAN access

From other machines on your network, replace localhost with your host’s IP address. Make sure your firewall permits incoming traffic on the MCP port.

stdio-only clients

Some MCP clients want a command to spawn instead of an HTTP URL. Use mcp-remote as a thin stdio→HTTP bridge:

npx -y mcp-remote http://localhost:5002/mcp

mcp-remote handles OAuth on the client’s behalf — no manual token generation needed.

Example client configurations

Claude Desktop

Claude Desktop reads MCP servers from claude_desktop_config.json. Add the mcp-remote command so Claude can negotiate OAuth automatically:

{
  "mcpServers": {
    "dbcode": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:5002/mcp"
      ]
    }
  }
}

On macOS the file lives at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows use %APPDATA%/Claude/claude_desktop_config.json. Restart Claude Desktop after editing.

GitHub Copilot CLI

Copilot CLI supports MCP via both HTTP and stdio. Add DBCode interactively or by editing the config file directly.

Interactive setup

Run /mcp add inside a Copilot CLI session, then provide:

• Server Name: dbcode
• Server Type: HTTP
• URL: http://localhost:5002/mcp
• Tools: *

Save with Ctrl+S.

Direct configuration

Edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "dbcode": {
      "type": "http",
      "url": "http://localhost:5002/mcp",
      "tools": ["*"]
    }
  }
}

If HTTP transport fails on your version, fall back to stdio via mcp-remote:

{
  "mcpServers": {
    "dbcode": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:5002/mcp"],
      "tools": ["*"]
    }
  }
}

Use /mcp show to verify the server is connected and /mcp show dbcode to list available tools.

Cursor

Cursor auto-registers DBCode — no .cursor/mcp.json entry needed. DBCode will appear in Cursor’s MCP UI as soon as the extension is installed.

If you ever need to configure it manually as a fallback, start the HTTP server and add:

{
  "mcpServers": {
    "dbcode": {
      "url": "http://localhost:5002/mcp"
    }
  }
}

Place this at .cursor/mcp.json for project-specific use or ~/.cursor/mcp.json globally. See the official Cursor MCP documentation for more.

VS Code

VS Code auto-registers DBCode — no manual configuration needed. If you ever need to configure it manually, start the HTTP server and add the URL to your mcp.json the same way as Cursor above.

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.

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.