covdbg MCP

MCP Server

• Section: Documentation > Integrations > MCP Server
• Canonical: https://covdbg.com/docs/integrations/mcp/

---

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

Register the local stdio server from your project directory:

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 AI quick-start prompt.

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, children, and libraries 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, targets that do their work in a child process, and code that lives in a DLL. A poorly scoped configuration can produce misleading coverage.

The improvement loop

1. Call guide, then discover to find executables and existing databases.
2. Call run with a target and configuration. It returns a run session immediately.
3. Call wait_run until it finishes. Each call returns after at most 30 seconds. A successful result includes a coverage session ID.
4. Call files to rank uncovered files, then code to read a file's uncovered segments with context.
5. Have the agent edit tests using its own coding tools, run the tests, and measure again.
6. 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.

To get set up with an AI agent, see the AI quick start. For shared reports and CI, see coverage reports.