Skip to content

fix: correct the client setup in the MCP guide #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shenxianpeng merged 1 commit into from
Sep 27, 2026
Merged

fix: correct the client setup in the MCP guide #48

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
fix: correct the client setup in the MCP guide 
The Claude Code tab told readers to put the server in
.claude/settings.local.json or ~/.claude/settings.json. Claude Code does
not read MCP servers from settings.json, so that config was silently
ignored. commit-check/commit-check-mcp#36 fixed the same mistake in that
README; the site kept it.

- Claude Code: `claude mcp add commit-check -- uvx commit-check-mcp`,
  with --scope project for a shared .mcp.json or --scope user for every
  project, and the .mcp.json block for writing it by hand.
- Zed: the key is context_servers, not mcp_servers.
- VS Code: a tab of its own, since its .vscode/mcp.json takes the
  servers key rather than mcpServers.
- The catch-all tab pointed at the README's #use-with-an-mcp-client,
  which commit-check/commit-check-mcp#38 renamed; it now links
  #where-each-client-keeps-it and names Continue, whose entry is YAML.
- "All tools are read-only" was not true: the two push checks may run
  git fetch to resolve a SHA. The page now says which two, and what that
  updates.

Checked against Claude Code's `claude mcp add --help` and its MCP docs,
Zed's MCP docs, and the commit-check-mcp README.
  • Loading branch information
@shenxianpeng
shenxianpeng committed Sep 27, 2026
commit af881879effda25c88b5d0340b98f8ec989d2f0e
48 changes: 40 additions & 8 deletions docs/guides/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,16 @@ The server runs over stdio and is started by the client. With

=== "Claude Code"

```json title=".claude/settings.local.json or ~/.claude/settings.json"
```console
$ claude mcp add commit-check -- uvx commit-check-mcp
```

That registers it for you, in this project. Add `--scope project` to write
it to a `.mcp.json` at the repository root instead, so the whole team gets
it once the file is committed, or `--scope user` for every project on your
machine. A hand-written `.mcp.json` holds the usual block:

```json title=".mcp.json"
{
"mcpServers": {
"commit-check": {
Expand All @@ -25,6 +34,8 @@ The server runs over stdio and is started by the client. With
}
```

Claude Code does not read MCP servers from `settings.json`.

=== "Cursor"

```json title=".cursor/mcp.json"
Expand All @@ -38,17 +49,27 @@ The server runs over stdio and is started by the client. With
}
```

=== "Claude Desktop, Windsurf, Cline, Roo Code"
=== "VS Code"

```json title=".vscode/mcp.json"
{
"servers": {
"commit-check": {
"type": "stdio",
"command": "uvx",
"args": ["commit-check-mcp"]
}
}
}
```

The same block, in each client's MCP settings file. The
[README](https://github.com/commit-check/commit-check-mcp#use-with-an-mcp-client)
lists the file for each.
The key is `servers`, not `mcpServers`. Copilot uses it in agent mode.

=== "Zed"

```json title="~/.config/zed/settings.json"
{
"mcp_servers": {
"context_servers": {
"commit-check": {
"command": "uvx",
"args": ["commit-check-mcp"]
Expand All @@ -57,14 +78,22 @@ The server runs over stdio and is started by the client. With
}
```

=== "Claude Desktop, Windsurf, Cline, Roo Code, Continue"

The `mcpServers` block from the Cursor tab, in each client's MCP settings
file; Continue takes it as a YAML list. The
[README](https://github.com/commit-check/commit-check-mcp#where-each-client-keeps-it)
lists the file and the format for each.

=== "Without uv"

```console
$ pip install commit-check-mcp
$ which commit-check-mcp
```

Then use that absolute path as the `command`, with no `args`.
Then use that absolute path as the `command`, with no `args`. On Windows,
`where commit-check-mcp` finds it.

## Make the agent use it

Expand Down Expand Up @@ -107,7 +136,10 @@ Every validation tool takes the same optional arguments:
- `config` — inline overrides, merged on top of the defaults and the file, for
a one-off stricter or looser check.

All tools are read-only. Nothing is committed, pushed or written.
No tool commits, pushes or changes the working tree. `validate_push_safety` and
`validate_repository_state` may run `git fetch` to resolve a SHA, which updates
`FETCH_HEAD` and the remote-tracking refs. The other six only read, and their
MCP annotations say so for clients that auto-approve read-only tools.

## The same rules, one step earlier

Expand Down