docs(readme): document claude code's one-time mcp server approval - #521
Conversation
install-mcp writes .mcp.json, but claude code only loads project-scope mcp servers after a per-user approval. the terminal cli prompts for it; the vscode extension never surfaces the prompt, so the vouch server sits at "pending approval" while the hooks keep working — a first install looks half-connected with no hint why. add the approval step to the main readme quickstart and the claude-code adapter readme: check with `claude mcp list`, approve via an interactive `claude` launch or a user-local .claude/settings.local.json with enabledMcpjsonServers (verified against claude code 2.1.206; the interactive route is the one to prefer in the vscode extension). the committed .claude/settings.json is ignored for that key (a repo can't approve its own servers), so the installer cannot do this step itself.
github-actions
Bot
added
docs
WalkthroughThe documentation updates explain one-time per-user MCP approval, VS Code prompt limitations, local approval configuration, and commands for verifying or debugging MCP server connectivity. ChangesMCP documentation
Estimated code review effort: 1 (Trivial) | ~3 minutes Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@adapters/claude-code/README.md`:
- Around line 77-81: Update the troubleshooting command in the Claude Code
README from “claude --debug-mcp” to the documented “claude --debug mcp” syntax,
while preserving the surrounding guidance about checking “claude mcp list”
first.
In `@README.md`:
- Around line 128-129: Update the one-time approval guidance in README.md lines
128-129 and adapters/claude-code/README.md lines 48-51 to include /mcp as a
recovery path alongside launching claude and configuring
.claude/settings.local.json. Preserve the existing approval, verification, and
VS Code reload instructions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: df53d9e5-6139-434d-8cbc-507e28742491
📒 Files selected for processing (2)
README.mdadapters/claude-code/README.md
| It should enumerate `kb_search`, `kb_propose_claim`, etc. If not, check | ||
| `claude mcp list` first: `vouch: vouch serve - ⏸ Pending approval` means | ||
| the one-time approval from step 2 hasn't happened yet (`✔ Connected` | ||
| once it has). For anything else, run `claude --debug-mcp` to see why | ||
| the server isn't loading. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '--- file list ---\n'
git ls-files | rg '^adapters/claude-code/README\.md$|(^|/)claude|package\.json|README\.md$' || true
printf '\n--- README excerpt ---\n'
sed -n '60,95p' adapters/claude-code/README.md
printf '\n--- search for debug syntax references ---\n'
rg -n --hidden --no-ignore-vcs 'debug-mcp|debug mcp|claude --debug|mcp list|claude mcp list' adapters/claude-code . || trueRepository: vouchdev/vouch
Length of output: 243
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo '--- README excerpt ---'
sed -n '68,90p' adapters/claude-code/README.md
echo
echo '--- search for debug syntax references ---'
rg -n --hidden --no-ignore-vcs 'debug-mcp|debug mcp|claude --debug|mcp list|claude mcp list' adapters/claude-code . || trueRepository: vouchdev/vouch
Length of output: 3197
🌐 Web query:
Claude Code debug MCP syntax "claude --debug-mcp" "claude --debug mcp" official documentation
💡 Result:
In Claude Code, the command to debug MCP issues is claude --debug mcp [1][2][3]. This command is used to surface underlying error messages—specifically the stderr output from an MCP server—that are otherwise hidden when a connection failure occurs [1][3]. It is particularly useful when a server appears to be connected but provides zero tools or is failing to respond, as it allows you to see the exact errors causing the failure [1][2]. Key debugging resources and commands include: 1. Diagnostic Command: Running claude --debug mcp prints detailed stderr output for MCP servers to help diagnose initialization or runtime errors [1][2][3]. 2. In-Session Diagnostics: Inside an active Claude Code session, use the /mcp command to see the status of all configured servers, check for connection failures, and verify tool availability [4][1][2]. 3. Verbose Mode: You can run claude --verbose to see the full exchange of messages between Claude Code and your MCP servers, which helps pinpoint where communication or tool execution is breaking [5]. 4. External Inspector: For isolating and testing servers independently of Claude Code, the official MCP Inspector can be used via npx @modelcontextprotocol/inspector <command> [5][6]. Note: Ensure that any command-line flags or arguments for MCP servers are placed correctly after the -- separator when adding them with claude mcp add, as incorrect placement is a common source of configuration errors [4][3]. There is also a third-party project called debug-mcp available on GitHub, but this is a separate utility and not an official built-in Claude Code command [7]. Always prioritize the native claude --debug mcp command for troubleshooting your local Claude Code MCP configuration [1][2].
Citations:
- 1: https://code.claude.com/docs/en/debug-your-config
- 2: https://code.claude.com/docs/en/debug-your-config.md
- 3: https://computingforgeeks.com/claude-code-mcp-servers-setup/
- 4: https://code.claude.com/docs/en/mcp
- 5: https://www.claudehub.fr/en/guides/claude-code-mcp/
- 6: https://modelcontextprotocol.io/docs/tools/debugging
- 7: https://github.com/rira100000000/debug-mcp
Use claude --debug mcp here. The current claude --debug-mcp form is not the documented Claude Code syntax, so this example can fail as written.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@adapters/claude-code/README.md` around lines 77 - 81, Update the
troubleshooting command in the Claude Code README from “claude --debug-mcp” to
the documented “claude --debug mcp” syntax, while preserving the surrounding
guidance about checking “claude mcp list” first.
| > **One-time approval.** Claude Code only loads a project's `.mcp.json` servers after a per-user approval. The terminal CLI prompts for it on the next `claude` launch — but the **VS Code extension never shows this prompt**, so the `kb.*` tools stay unavailable there while the hooks keep working (which makes it easy to think vouch is connected when it isn't). If `claude mcp list` run inside the project shows `vouch … ⏸ Pending approval`, either run `claude` in the project folder from any terminal and accept the prompt, or create `.claude/settings.local.json` (user-local, not committed) with `{"enabledMcpjsonServers": ["vouch"]}`. The same key in the committed `.claude/settings.json` is deliberately ignored — a repo can't approve its own servers — which is why `install-mcp` can't do this step for you. Verify with `claude mcp list` (`✔ Connected`), then reload the VS Code window. | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== README.md excerpt ==\n'
sed -n '118,136p' README.md
printf '\n== adapters/claude-code/README.md excerpt ==\n'
sed -n '40,58p' adapters/claude-code/README.md
printf '\n== search for mcp approval references ==\n'
rg -n --hidden --glob '!**/.git/**' --glob '!*node_modules*' --glob '!**/dist/**' --glob '!**/build/**' '(/mcp|enabledMcpjsonServers|Pending approval|claude mcp list|settings\.local\.json)' .Repository: vouchdev/vouch
Length of output: 8886
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== adapters/claude-code/README.md excerpt around approval troubleshooting ==\n'
sed -n '70,90p' adapters/claude-code/README.md
printf '\n== README.md excerpt around the approval note ==\n'
sed -n '124,132p' README.mdRepository: vouchdev/vouch
Length of output: 2350
🌐 Web query:
Claude Code mcp approval dismissed prompt /mcp site:code.claude.com
💡 Result:
In Claude Code, project-scoped MCP servers defined in a.mcp.json file require a one-time user approval [1][2]. If you dismiss the initial approval prompt, the server will remain disabled [1][2]. To resolve this and approve a dismissed MCP server: 1. Run the /mcp command within your active Claude Code session [1][2][3]. 2. This command opens an interactive list of all configured MCP servers [3][4]. 3. From this interface, you can check the connection status and approve the server to enable it for the current project [1][2][4]. If a server shows as failed or fails to connect after approval, you can use the same /mcp interface to attempt a reconnection or inspect error details [1][5].
Citations:
- 1: https://code.claude.com/docs/en/debug-your-config.md
- 2: https://code.claude.com/docs/en/debug-your-config
- 3: https://code.claude.com/docs/en/commands.md
- 4: https://code.claude.com/docs/en/mcp-servers
- 5: https://code.claude.com/docs/en/mcp-quickstart
Add /mcp as the dismissed-prompt recovery path. Update both docs to mention /mcp alongside claude launch and .claude/settings.local.json:
README.md#L128-L129adapters/claude-code/README.md#L48-L51
📍 Affects 2 files
README.md#L128-L129(this comment)adapters/claude-code/README.md#L48-L51
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 128 - 129, Update the one-time approval guidance in
README.md lines 128-129 and adapters/claude-code/README.md lines 48-51 to
include /mcp as a recovery path alongside launching claude and configuring
.claude/settings.local.json. Preserve the existing approval, verification, and
VS Code reload instructions.
1 participant
a first-time user following the readme on a fresh project gets a working install whose
kb.*mcp tools never appear in the vs code extension. claude code gates project-scope.mcp.jsonservers behind a one-time per-user approval; the terminal cli prompts for it on launch, but the extension never surfaces the prompt, so the server sits at⏸ pending approvalindefinitely. the hooks need no approval and keep firing, which makes the install look connected when it isn't — reproduced end-to-end on a real project (claude code 2.1.206).this adds the missing step to the two readmes a new user actually reads. the quickstart gains a short "one-time approval" note after the install-mcp step: check with
claude mcp list, then either runclaudein the project folder and accept the prompt, or drop{"enabledMcpjsonServers": ["vouch"]}into user-local.claude/settings.local.json. the adapter readme's "pick it up next time you open the project" sentence now tells the truth, and its verify section points atclaude mcp listbefore--debug-mcp.both remedies were a/b verified: the approval is honored from
~/.claude.jsonand fromsettings.local.json, and deliberately ignored in the committed.claude/settings.json— a repo can't approve its own servers — which is why install-mcp cannot do this step for the user and the readme has to say it.docs-only, branched off main per the repo convention.
Summary by CodeRabbit
kb.*tools in the VS Code extension.claude mcp listand debug mode.