# 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:

```powershell
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:

```json
{
  "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:

```powershell
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](/docs/getting-started/ai-quick-start/).

## 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

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.

For the broader workflow, see [AI coverage](/ai-coverage/). For shared reports and CI, see [coverage reports](/coverage-reports/).