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).