DBHawk MCP — Claude Code plugin + demo connector

Gives an AI assistant read-only access to DBHawk: list the datasources a user is assigned, browse schema/tables/columns, run read-only queries (with the user's access control and column masking applied), and use HawkAI text-to-SQL / optimize / format.

It's a thin bridge over the existing DBHawk REST surface at /api/v2/mcp/**. No write path exists; DBHawk rejects any statement that modifies data or schema, whatever role the token owner has.

Auth is two steps. DBHAWK_TOKEN is a personal token (dbh_<id>.<secret>), 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. When the JWT expires the next call gets a 401, and the server 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-<version>.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 (masked; stored in your OS keychain), Default Datasource (optional) — and save.

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

Demo prompts: "Which datasources do I have?" → "Show tables in schema public of Postgres-Demo" → "What columns does customers have?" → "How many orders last month by status?" (text-to-SQL → run).

For maintainers — publish & rebuild

Publish the marketplace

cd dbhawk-mcp-plugin
git init && git add . && git commit -m "DBHawk MCP plugin"
git remote add origin git@github.com:datasparc/dbhawk-mcp-plugin.git
git push -u origin main

Users then run the two /plugin commands above. To list it in Anthropic's curated claude-plugins-official directory, submit it via the plugin directory submission form (separate review); your own marketplace works immediately without that.

Rebuild the bundle (after editing index.js)

cd dbhawk/mcp-server
npm install        # once, pulls the SDK + esbuild (build-time only)
npm run build      # regenerates dist/dbhawk-mcp.mjs
git add dist/dbhawk-mcp.mjs && git commit -m "rebuild bundle"

dist/dbhawk-mcp.mjs is committed on purpose — it is the artifact users run. node_modules/ is not.

Build & release the desktop extension (.mcpb)

The mcpb/ folder is the extension source: mcpb/manifest.json (declares the user_config fields shown in Desktop's settings form) plus mcpb/server/dbhawk-mcp.mjs (a copy of the same dist/ bundle). After rebuilding the bundle, refresh the copy, then pack and release:

cp dbhawk/mcp-server/dist/dbhawk-mcp.mjs mcpb/server/dbhawk-mcp.mjs   # keep the copy in sync
npx @anthropic-ai/mcpb validate mcpb/manifest.json                   # optional sanity check
npx @anthropic-ai/mcpb pack mcpb dbhawk-<version>.mcpb                # produces the .mcpb

gh release create v<version> dbhawk-<version>.mcpb \
  --title "DBHawk <version>" --notes "DBHawk MCP desktop extension"

Bump version in mcpb/manifest.json for every release (Desktop keys upgrades off it). The .mcpb is git-ignored — it ships as a Release asset, not in the tree. Keep mcpb/manifest.json's version in step with dbhawk/.claude-plugin/plugin.json so the plugin and the extension stay aligned.

Troubleshooting

• token exchange failed: 401/403 — the personal DBHAWK_TOKEN is wrong, revoked or expired, the user isn't in the MCP access group, or (SSO/SAML users) the sign-in re-validation window lapsed — log in to DBHawk once via your identity provider, the same token then works again. Reissue if needed.
• DBHawk API 401/403 (after exchange) — wrong scope or the user lacks ACCESS_TO_DATA.
• Only read-only statements… — a write/DDL statement was attempted; expected, MCP is read-only.
• Missing configuration on startup — DBHAWK_BASE_URL / DBHAWK_TOKEN not set.
• Server not listed in /mcp — confirm Node ≥ 18 and that dist/dbhawk-mcp.mjs exists in the installed plugin. In Claude Desktop, use the full path to node (Desktop has a minimal PATH).