DBCode - Docs - Model Context Protocol (MCP)

Model Context Protocol (MCP) is a protocol that enables complex AI interactions, and tool execution on your behalf, inside and outside of Visual Studio Code. It allows you to interact with AI models and tools in a more natural and intuitive way, without the need for manual coding or configuration.

Step-by-Step: Setting Up MCP in DBCode

1. Review Your MCP Settings

Before starting, make sure your settings are configured correctly:

Open DBCode MCP Settings
Default port is 5002
Choose the authentication mode under dbcode.ai.mcp.authorization:
- OAuth (recommended) → secure OAuth 2.1 approval flow handled inside VS Code
- None → no authentication, for trusted local setups only

2. Start the MCP Server

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

DBCode: MCP Start Server

The MCP server listens on a single HTTP endpoint:

http://localhost:5002/mcp

When running in OAuth mode the discovery endpoint is also available at:

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

You’re ready to connect a tool to DBCode using Streamable HTTP transport.

3. Connect a Client to MCP

DBCode uses the Streamable HTTP transport. Clients connect over plain HTTP and either negotiate OAuth or skip auth entirely based on your MCP setting.

OAuth-aware HTTP clients

Most MCP clients handle OAuth discovery automatically. Configure them to use the MCP endpoint with HTTP transport and they’ll complete the flow without additional setup:

MCP endpoint: http://localhost:5002/mcp
Transport: http

If your client requires a discovery document, manually enter http://localhost:5002/.well-known/oauth-authorization-server.

On first connection VS Code displays an approval dialog showing the client ID, redirect URI, and requested scopes. Approving the dialog mints an access token that the client reuses automatically. Denying the dialog aborts the handshake.

HTTP clients in “None” mode

If you switched dbcode.ai.mcp.authorization to None, point clients directly at the MCP endpoint: http://localhost:5002/mcp. No authentication headers or query parameters are required.

stdio-only clients

Some MCP clients expect a command to execute instead of connecting over HTTP directly. Use mcp-remote helper, which supports both OAuth and no-auth modes without extra flags:

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

Provide this command to your client wherever it requests an MCP command/args. mcp-remote handles the OAuth approval flow by launching the HTTP transport under the hood, so no manual token generation is necessary.

4. Stopping the MCP Server

When finished, stop the server using the command palette:

DBCode: MCP Stop Server

Authentication Methods

The MCP server supports two authentication modes:

OAuth Authentication (Recommended)

OAuth is the default mode. Clients discover the authorization and token endpoints via /.well-known metadata and request access using the standard Authorization Code + PKCE flow. When a client asks for access, VS Code shows an approval dialog. Tokens are stored securely and automatically attached to future requests—no manual token generation commands are required.

No Authentication

All requests to /mcp are accepted without credentials. This mode is only suitable for local development or trusted environments. Remote or shared environments should always use OAuth.

Example Client Configurations

Cursor

Cursor supports MCP through JSON configuration files. You can configure DBCode’s MCP server in two ways—HTTP transport (OAuth) or stdio (via mcp-remote).

Project-Specific Configuration (HTTP + OAuth)

Create a .cursor/mcp.json file in your project directory:

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

Project-Specific Configuration (stdio via `mcp-remote`)

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

You can also place these configurations under ~/.cursor/mcp.json for a global setup. Update the http://localhost:5002 portion if you changed the MCP port in settings.

For more information about MCP configuration in Cursor, see the official Cursor MCP documentation.

Claude Desktop

Claude Desktop reads MCP settings from claude_desktop_config.json. Add or update the file with 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 so it reloads the configuration.

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)

The AI will use 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.

Model Context Protocol (MCP)