Skip to content

The MCP server

verlato serve runs a Model Context Protocol server on stdio, so agents such as GitHub Copilot, Claude and other MCP clients can review and write release notes with Verlato's tools. verlato-mcp, installed by the Python package, is the same server. It is part of the native program and needs nothing else installed.

The server works on the repository in its working directory, so start it from (or configure its cwd as) the repository root.

Connecting a client

VS Code (Copilot agent mode)

.vscode/mcp.json in the repository:

{
  "servers": {
    "verlato": {
      "type": "stdio",
      "command": "verlato",
      "args": ["serve"]
    }
  }
}

VS Code starts the server in the workspace folder. If verlato is not on PATH, give its full path (for example a release bundle's executable, or ${workspaceFolder}/.venv/bin/verlato-mcp).

Claude Code

claude mcp add verlato -- verlato serve

Other clients

Any client that launches stdio servers can use this shape:

{
  "mcpServers": {
    "verlato": {
      "command": "verlato",
      "args": ["serve"],
      "cwd": "/path/to/your/repository"
    }
  }
}

The extension's Verlato: Start MCP Server command runs verlato serve in a terminal and shows its status in the Control view. Clients that launch their own server (all of the above) do not need it; to check a connected client, call verlato_service_health.

Tools

Every range tool takes base (required) and head (default HEAD).

Tool What it does
verlato_service_health backend health and version
verlato_service_info state statistics, configured targets and the diff engine
verlato_scan_unpublished_changes unpublished change items in a range (read-only)
verlato_reconcile_preview a lightweight preview of unpublished changes
verlato_get_draft_document the structured draft (version, include_confidence, include_provenance, model_provider)
verlato_preview_release_notes the rendered GitHub release notes
verlato_apply_draft write the draft to a target or file
verlato_update_review_state set an item's status, summary or reviewer
verlato_request_model_input ask the configured model for a summary for one item
verlato_list_suggestion_items compact items with their changed files (include_files)
verlato_get_suggestion_item one item's metadata, commits, files and semantic review
verlato_get_file_semantic_diff the IntentumDiff semantic diff of one file in one item
verlato_search_semantic_diff search one item's semantic diff for a symbol or term
verlato_draft_conventional_commit draft a Conventional Commit message for one commit (sha)
verlato_draft_conventional_commits the same for several commits (shas, or the whole range)

With the legacy git diff engine, two raw-patch tools replace the semantic ones: verlato_get_file_patch and verlato_search_item_diff.

Agents get IntentumDiff's semantic diff, not raw patches: each file's meaningful changes with their enclosing symbols, refactorings, moved code and ignored formatting. The server's instructions and its prompt tell agents to base release notes on it and never to describe moved code, refactorings or formatting as new behaviour. MCP clients count as remote models, so change descriptions (which can quote source) are only included under the trusted-provider-patch privacy mode.

Resources and prompts

Name What it is
verlato://overview a structured overview of the server and its capabilities
verlato://sample-config a sample verlato.json
verlato://guidance/{name} workspace guidance: readme, agent, architecture, copilot, skill
prompt verlato_review_request walks an agent through reviewing and writing release notes for a range (base, head, version)

An agent session

A typical exchange: the agent calls verlato_list_suggestion_items for v1.0.0..HEAD, reads verlato_get_suggestion_item and verlato_get_file_semantic_diff for each item that needs review, writes better summaries with verlato_update_review_state, and finally calls verlato_apply_draft with target: "changelog". The protocol details are in Service and MCP protocol.