Dbhawk

DBHawk MCP — Claude Code plugin + demo connector

Gives an AI assistant access to DBHawk: list the datasources a user is assigned, browse schema/tables/columns, run queries (with the user's access control and column masking applied), and use DBHawk AI text-to-SQL / optimize / format. Data or schema changes are possible only when the user's MCP tier allows them — the default tier is read-only (see Reads, writes and MCP tiers).

It's a thin bridge over the existing DBHawk REST surface at /api/v2/mcp/**. DBHawk decides what runs: every statement is classified and checked against the tier of the user's groups, whatever role the token owner has.

Sign in, or a personal token. Leave DBHAWK_TOKEN empty and the server signs in to DBHawk through the browser on the first tool call: the DBHawk login page opens (password, LDAP, 2FA or SSO - whatever your DBHawk offers), you approve the access once, and the server keeps a refresh token in your user profile for the next start (%APPDATA%\dbhawk-mcp on Windows, ~/Library/Application Support/dbhawk-mcp on macOS, ~/.config/dbhawk-mcp on Linux). This needs DBHawk 7.0.1 with the MCP connector; what you may do is decided by your MCP tier, exactly as with a token. See UPGRADE-7.1.0.md.

With a personal token, auth is two steps. DBHAWK_TOKEN is a personal token (dbh_ . ), not a JWT — the MCP endpoints won't accept it directly. On its first call the server exchanges it for a short-lived JWT at POST /api/v2/auth/token/exchange (sending the personal token in the X-API-Token header), caches that JWT, and sends it as the Bearer for every /api/v2/mcp/** call. Shortly before the JWT's exp the server exchanges a fresh one up front; if a call still gets a 401 it re-exchanges and retries once — transparent to you.

dbhawk-mcp-plugin/                 <- this folder = a Claude Code "marketplace" (push it to git)

├── .claude-plugin/marketplace.json └── dbhawk/ <- the actual plugin (installed by users) ├── .claude-plugin/plugin.json ├── .mcp.json <- declares the "dbhawk" stdio MCP server └── mcp-server/ ├── index.js <- source ├── package.json <- build tooling (maintainers only) └── dist/dbhawk-mcp.mjs <- COMMITTED self-contained bundle (what users run; no npm install)

The bundle in dist/ inlines every dependency, so a bare `git clone` runs with zero install — that's what makes /plugin install work.

For users — install

Claude Code (from the marketplace)

Once this repo is on GitHub (see *Publish* below), point Claude Code at it and install:

/plugin marketplace add datasparc/dbhawk-mcp-plugin

/plugin install dbhawk@dbhawk-marketplace

dbhawk is the plugin name, dbhawk-marketplace is the marketplace name (from marketplace.json). Then set the connection (see *Configure*) and check the tools are live with /mcp.

Prefer to try it without a git host? Load the local folder for one session:

claude --plugin-dir ./dbhawk-mcp-plugin/dbhawk

Claude Desktop (extension, .mcpb) — recommended

Claude Desktop installs this as a Desktop Extension with a proper GUI settings form (no JSON editing). It's the same MCP server, packaged as an .mcpb bundle.

1. Download dbhawk- .mcpb from the Releases page.
2. In Claude Desktop: Settings → Extensions → Advanced settings → Install and pick the file (or just drag the .mcpb onto the Extensions window).
3. Fill in the form — DBHawk Base URL, API Token (optional; masked, stored in your OS keychain - leave it empty to sign in through the browser instead), Default Datasource (optional) — and save.
4. With no token, the first DBHawk tool call opens the DBHawk sign-in in your browser: sign in, click Allow, and repeat the request if Claude reported that it was waiting for the sign-in.

Claude Desktop does not auto-update file-installed extensions: to upgrade, download the newer .mcpb and install it again. This is independent of the Claude Code plugin — you don't need the marketplace plugin installed.

Claude Desktop (manual config, advanced)

Prefer to wire it by hand instead of the .mcpb? Point Desktop at the bundle with an absolute path. Edit claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{

"mcpServers": { "dbhawk": { "command": "C:\\Program Files\\nodejs\\node.exe", "args": ["C:\\...\\dbhawk-mcp-plugin\\dbhawk\\mcp-server\\dist\\dbhawk-mcp.mjs"], "env": { "DBHAWK_BASE_URL": "https://demo.dbhawk.example.com", "DBHAWK_TOKEN": "PASTE_MCP_TOKEN_HERE", "DBHAWK_DEFAULT_DATASOURCE": "" } } } }

Restart Claude Desktop fully (including the tray icon).

Configure

The server needs three values (the token owner needs ACCESS_TO_DATA):

Claude Code — guided setup dialog (recommended)

The plugin declares these as userConfig fields in dbhawk/.claude-plugin/plugin.json, so Claude Code prompts for them when you enable the plugin — the token field is sensitive, so it's masked on entry and stored in secure storage (OS keychain / ~/.claude/.credentials.json), never in settings.json or git. dbhawk/.mcp.json wires them in via ${user_config.dbhawk_token} etc.

To re-enter or change them later, re-enable the plugin, or set them non-interactively:

claude plugin install dbhawk@dbhawk-marketplace \

--config dbhawk_base_url=https://demo.dbhawk.example.com \ --config dbhawk_token=dbh_... \ --config dbhawk_default_datasource=

Claude Desktop — environment variables

Desktop doesn't understand plugins or userConfig — pass the three values as env in the claude_desktop_config.json block shown above.

Tools

The job tools need a DBHawk server with the MCP job scheduler (migration 87 adds view_jobs, manage_jobs and run_jobs, granted to the *Destructive / admin* tier only) and the Job Scheduler license.

The job tools are interactive where the client allows it, but always in plain text:

• Job screen (MCP Apps): off. The HTML screen is commented out - no ui://dbhawk/jobs resource, and no tool carries _meta.ui.resourceUri. A client that shows MCP Apps is asked in a form like any other. To bring it back, uncomment the marked blocks in mcp-server/index.js.
• Forms (clients that support MCP elicitation): create_job asks you for whatever the model left out (datasource, name, SQL, schedule, format, delivery). The schedule and the output are never taken from the model unseen: when it brings a valid cron, a format and a delivery, you get one question instead ("Schedule ... Result ... Delivery ... Is that right?"), and clearing the box opens the whole form on what it proposed. update_job with only a job id opens the job in a form, and a call your MCP tier wants confirmed asks you in a form. Declining changes nothing.
• Chat dialog (every other client): create_job is filled in with you in the chat, one question at a time - DBHawk answers with the next question (datasource, name, SQL, schedule, format, delivery) instead of an error, and the assistant puts it to you and calls the tool again with your answer. Each is asked only where the model has not been told it; the schedule, the format and the delivery are never taken from it unseen - where it has all three, they go to you as one question ("Is that right?"), and if you want one of them changed the assistant calls again without it and DBHawk asks you for it. A cron DBHawk cannot read is asked again with the reason, and the confirmation your tier wants is still asked before anything is created.

mcp-server/ui/jobs.html stays in the repository (a copy of DBHawk's own src/main/resources/mcp/ui/jobs.html) but is no longer bundled or served.

Reads, writes and MCP tiers

What a user may do is set in DBHawk, per user group, by its MCP tier (Admin → MCP Management → MCP Tiers). The default tier is read-only; higher tiers add EXPLAIN, DML (INSERT / UPDATE / DELETE / MERGE), DDL and admin operations. get_permissions tells the model what its tier allows.

Reads and writes are separate tools on purpose. run_query is annotated read-only (readOnlyHint), and DBHawk refuses a write sent through it even when the tier allows one. execute_statement is annotated destructive (destructiveHint), so MCP clients such as Claude ask the user before each call - keep it that way, do not "always allow" it. When the tier also asks for confirmation, DBHawk answers the first call with `{ confirmationRequir