MCP Server

Every Query Doctor instance serves an MCP server at /mcp. Point an MCP client such as Claude Code at it and the agent gets Query Doctor as tools: run a project health check, connect a database, and read or triage your CI runs.

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

The commands below write <your-query-doctor-url>, the address of your Query Doctor instance: https://cloud.querydoctor.com on the hosted service, or the address you open your instance at if you self-host.

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; everything that touches a project requires an authorized session (see Authorization).

Install

Register the endpoint with Claude Code:

claude mcp add --transport http query-doctor <your-query-doctor-url>/mcp

Verify it connected:

claude mcp get query-doctor
# Status: ✓ Connected
# Transport: http
# URL: <your-query-doctor-url>/mcp

Caution

If Claude Code was already running, restart it so the client picks up the newly registered server.

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": "<your-query-doctor-url>/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.
• doctor, connect_database, and the writes (triage_query, set_comparison_branch, approve_schema_change) 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

• 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.
• connect_database — connects a Postgres database to a project. The instance stores the connection string and starts a Collector against that database itself. The result says what became of the launch — starting, running, checked in, or refused with the reason and what to do about it. Call it again with only the project to read the state back.
• approve_schema_change — approves the migration in a CI run’s pull request, clearing the schema-drift gate. It covers every schema change that run reported, and amending the migration withdraws it. CI has to run again for the check to clear.
• CI tools — read the runs a Collector 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.
• optimize_query — plans one query on a Postgres instance Query Doctor runs. Your agent passes the schema as schemaSql, the output of pg_dump --schema-only --no-owner -t <table> -e <extension> against your local database, and optionally an unapplied migration as pendingSchemaSql. Name a project to cost under its production statistics. Without one, every table gets an assumed size, and caveats says so. The answer’s provenance says which statistics it used.

Companion skill (recommended)

Every instance serves an agent skill at <your-query-doctor-url>/skill.md, rendered with that instance’s own address in the claude mcp add command it carries. It takes an agent from an unconfigured repository to a CI run it can read: register the server, create the project, write the workflow, then read what CI found. Once the repository is wired, it tells the agent to check a plan before claiming a query is fast or an index helps.

Skills are loaded from .claude/skills/. Drop it into your project, or into ~/.claude/skills/ for every project:

mkdir -p .claude/skills/query-doctor
curl -fsSL <your-query-doctor-url>/skill.md \
  -o .claude/skills/query-doctor/SKILL.md

Take it from your own instance. docs.querydoctor.com/skill.md is the same file rendered for the hosted service, so it points an agent at cloud.querydoctor.com.

Restart your MCP client after adding it.

An agent that can fetch a URL needs no install — point it at the same address and it can follow the guide directly.

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; the writes and the project tools need a session.
• optimize_query says the schema could not be loaded — the error quotes the statement Postgres rejected. pg_dump -t leaves out objects the table depends on: pass -e <extension> for each extension it uses. When the error names an enum type, a function or a sequence, drop -t and dump the whole schema.