MCP Server

The covdbg MCP server lets an AI coding agent measure native C++ coverage on Windows and read the results through structured tools.

Start the server

The server is part of the covdbg executable:

covdbg mcp

Configure your MCP client to launch covdbg with the argument mcp, using your project as its working directory. The server uses standard input and output, with one JSON object per line. It is not an HTTP service. discover searches the directory the server was started in; pass --workspace <dir> when the client cannot start it inside the project.

For a client that reads a project .mcp.json file:

{
  "mcpServers": {
    "covdbg": {
      "command": "covdbg",
      "args": ["mcp"]
    }
  }
}

The executable must be on the client's PATH, or command must name its full path. Configuration file names and registration steps depend on the client.

Claude Code

claude mcp add covdbg -- covdbg mcp

Check the installed client's help for supported scope options and inspect existing MCP settings before changing them. After connecting, call guide before starting a coverage run. For help with setup, use the copyable AI quick-start prompts.

Prerequisites for a run

Windows and an existing executable with PDB debug symbols.
A developer sign-in through covdbg login, or COVDBG_PROJECT_TOKEN in the server environment for CI.
A .covdbg.yaml beside the target executable, or an explicit config_path in the run call.

Read the server's guide before measuring. Without a topic it explains the workflow. The topics config, excludes, baseline, merging, uncovered, and children cover writing a .covdbg.yaml, keeping the CRT and Windows SDK out of the report, static-library code no test binary links, measuring a whole suite, finding dead code with SQL, and targets that do their work in a child process. A poorly scoped configuration can produce misleading coverage.

The improvement loop

Call guide, then discover to find executables and existing databases.
Call run with a target and configuration. It returns a run session immediately.
Call wait_run until it finishes. Each call returns after at most 30 seconds. A successful result includes a coverage session ID.
Call files to rank uncovered files, then code to read a file's uncovered segments with context.
Have the agent edit tests using its own coding tools, run the tests, and measure again.
Review both the test result and coverage change. Close sessions when finished.

The MCP server does not edit source or generate tests itself. It supplies the measurements and context that the connected coding agent can use.

Tool reference

Tool	Purpose	Main inputs
`guide`	Read workflow and configuration guidance	Optional `topic`
`discover`	Find executables and coverage databases	Optional `root`
`run`	Start a coverage run	`target`; optional `target_arguments`, `config_path`, `output_path`, `follow_children`
`wait_run`	Wait briefly or collect the completed result	`session_id`; optional `timeout_seconds`
`cancel_run`	Terminate a run	`session_id`
`open_coverage`	Open an existing database read-only	`path`
`files`	Rank files by uncovered lines	`session_id`; optional `limit`, `max_coverage_percent`
`code`	Read uncovered source segments with context	`session_id`, `file_path`
`query`	Run one read-only SQL statement	`session_id`, `sql`; optional `max_rows`
`merge`	Combine databases	`input_paths`, `output_path`
`close`	Release a run or coverage session	`session_id`

Pass a filePath returned by files directly to code. Missing source is reported explicitly. query rejects writes and statements such as ATTACH that reach outside the open database.

Set follow_children on run when the target is a launcher: a script host, a shell, or a test runner that spawns the process doing the real work. Without it only the launcher is measured. It is off by default because every child is instrumented, and a target that shells out repeatedly pays for each one; the children guide topic explains the cost. It has the same effect as --follow-children on the command line or settings.follow_children in .covdbg.yaml.

Sessions and outputs

Run IDs begin with run-; open coverage IDs begin with covdb-. Sessions last for the server process. A successful wait_run opens the output database automatically. The server holds up to 32 open coverage sessions and 8 runs in flight. A run takes a slot only while it is running; a finished run keeps its result but no longer counts, so a suite of many short runs needs no close between them.

A wait_run call blocks for at most 30 seconds, whatever timeout_seconds asks for, because the server answers one call at a time and a longer wait would keep cancel_run unreachable. If its response says stillRunning, call again. Completed outcomes distinguish success, no_functions_to_track, license_failure, and error.

By default, runs use distinct temporary output files. An explicit output_path selects a destination. COVDBG_OUTPUT selects a fixed default location; avoid reusing one location across a suite because later runs can overwrite earlier results. Merge the separate databases instead.

Important workflow boundaries

Coverage success is not test success. covdbg's exit code does not propagate the target's exit code. Check the test runner's result separately and read the target output.
Cancellation loses the coverage. The database is written when the run completes; cancelling a run produces no coverage database.
The server launches a target. It cannot attach to an already running process or pause at a breakpoint for inspection.
Source context is returned to your AI client. A local MCP server does not imply the client's model processes that context locally.
Older incompatible database schemas are rejected. Regenerate coverage with the matching build.

For the broader workflow, see AI coverage. For shared reports and CI, see coverage reports.