MCP Server

Query Doctor runs a hosted MCP server at https://api.querydoctor.com/mcp. Point an MCP client such as Claude Code at it and the agent gets Query Doctor as tools: optimize a query against your own database, run a project health check, and read or triage your CI runs.

Nothing to install or run locally: the server is hosted and you register its URL. It speaks Streamable HTTP, so any MCP client that supports the HTTP transport works.

Prerequisites

An MCP client that supports the HTTP transport and OAuth — e.g. Claude Code (claude CLI).
A Query Doctor account for the tools that act on your projects. The CI read tools work without signing in; optimizing a query and writing triage state require an authorized session (see Authorization).
To optimize queries: a project with the analyzer connected. optimize_query relays to the analyzer you run against your database — see Connect a database and CI integration.

Install

claude mcp add --transport http query-doctor https://api.querydoctor.com/mcp

Verify it connected:

claude mcp get query-doctor
# Status: ✓ Connected
# Transport: http
# URL: https://api.querydoctor.com/mcp

Other MCP clients

Any HTTP-transport MCP client works — register the same URL. For clients configured by JSON, the equivalent entry is:

{
  "mcpServers": {
    "query-doctor": {
      "type": "http",
      "url": "https://api.querydoctor.com/mcp"
    }
  }
}

Authorization

The server splits tools by whether they act on your account:

Read-only CI tools (find_regressions, get_ci_run, get_query_status, …) work anonymously — no sign-in needed.
optimize_query, doctor, and the triage writes (triage_query, set_comparison_branch) act on your projects and require an authorized session.

The server uses OAuth. The first time your agent calls a tool that needs a session, the client opens your browser to sign in. You don’t paste a token or set an environment variable. In Claude Code you can also start this from /mcp, which shows the server’s authorization status.

What the tools do

optimize_query — relays a query to your project’s running analyzer. The analyzer plans it against your own database and returns the base cost, whether a new index helps (with the CREATE INDEX definition and projected cost), and the before/after explain plans. The query and its data never reach Query Doctor’s servers. Returns a needs_setup result if no analyzer is connected for the project.
doctor — health check for a project: its linked database, CI and comparison-branch state, the latest run, whether SQLCommenter tags are present, and a list of things to fix. Each item carries the tool call that fixes it.
CI tools — read the runs the analyzer recorded: find_regressions, list_ci_runs, get_ci_run, get_ci_query, review_ci_run, get_latest_ci_run, get_query_history, get_query_status, get_repo_config. triage_query and set_comparison_branch write triage state.

Companion skill (recommended)

Query Doctor ships an agent skill so your agent reaches for these tools on its own. When it writes or reviews code that builds a query, adds a migration, or defines an index, it validates the plan and index choices before handing the code back.

Skills are loaded from .claude/skills/. Drop the published skill into your project (or ~/.claude/skills/ for every project):

mkdir -p .claude/skills/query-doctor
curl -fsSL https://unpkg.com/@query-doctor/mcp-server/skill/SKILL.md \
  -o .claude/skills/query-doctor/SKILL.md

Restart your MCP client after adding it.

Removing

claude mcp remove query-doctor

Troubleshooting

Tools don’t appear in the agent — confirm claude mcp get query-doctor reports ✓ Connected, then restart the client.
A tool returns an authorization error — sign in via the browser flow (or /mcp in Claude Code). The CI read tools work anonymously; optimize_query and the triage writes need a session.
optimize_query returns needs_setup — no analyzer is connected for that project. Start the analyzer against your database (see CI integration) and retry.