docs: register MCP servers at user scope, not the default
Claude Code's default MCP scope is `local`, which is per-project: the server is stored under that directory in ~/.claude.json and does not appear in `claude mcp list` from anywhere else. docs/LOCAL.md showed the default and so produced exactly that confusion. User scope is right here — the point is to ask about coursework from any directory. Project scope would write a .mcp.json into the repo, which is wrong when the HTTP config carries a bearer token. Also adds the symptom and the fix, since "it is not in the list" has one overwhelmingly likely cause. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -39,25 +39,31 @@ Claude Code supports MCP over stdio, SSE and HTTP. The VS Code extension runs
|
||||
the same Claude Code underneath, so it reads the same configuration — register
|
||||
once and both work.
|
||||
|
||||
**Use `--scope user`.** Claude Code's default scope is `local`, which is
|
||||
*per-project*: the server is stored under that directory in `~/.claude.json` and
|
||||
`claude mcp list` will not show it from anywhere else. Since the point is to ask
|
||||
about your coursework from wherever you happen to be, user scope is what you
|
||||
want. (`project` scope would write a `.mcp.json` into the repo — wrong here,
|
||||
because the HTTP config carries a token.)
|
||||
|
||||
**HTTP — matches the deployed setup:**
|
||||
|
||||
```bash
|
||||
claude mcp add --transport http schulcloud http://127.0.0.1:8080/mcp \
|
||||
claude mcp add --scope user --transport http schulcloud http://127.0.0.1:8080/mcp \
|
||||
--header "Authorization: Bearer $MCP_AUTH_TOKEN"
|
||||
```
|
||||
|
||||
**stdio — no server or Docker needed:**
|
||||
|
||||
```bash
|
||||
claude mcp add schulcloud-stdio \
|
||||
claude mcp add --scope user schulcloud-stdio \
|
||||
-e DATABASE_URL=postgresql://schulcloud:schulcloud@127.0.0.1:55432/schulcloud \
|
||||
-- node --env-file=/absolute/path/to/.env /absolute/path/to/dist/bin/stdio.js
|
||||
```
|
||||
|
||||
`--env-file` keeps the JWT in `.env` rather than copying it into the MCP config.
|
||||
The HTTP form has no such option — its header holds the token — so leave it at
|
||||
the default `local` scope, which writes to `~/.claude.json` rather than a
|
||||
`.mcp.json` that would be committed.
|
||||
The HTTP form has no equivalent — its header holds the token — so that token
|
||||
lives in `~/.claude.json`.
|
||||
|
||||
Check it:
|
||||
|
||||
@@ -66,6 +72,10 @@ claude mcp list # schulcloud: http://127.0.0.1:8080/mcp (HTTP) - ✔ Conne
|
||||
claude mcp get schulcloud
|
||||
```
|
||||
|
||||
If `claude mcp list` does not show it, the usual cause is scope: run
|
||||
`claude mcp list` from the directory you added it in, and if it appears there,
|
||||
re-add it with `--scope user`.
|
||||
|
||||
Then just ask: *"which courses am I in?"*, *"what's due this week?"*, *"find the
|
||||
material about Verschlüsselung"*. Inside a session, `/mcp` lists the servers and
|
||||
their tools.
|
||||
|
||||
Reference in New Issue
Block a user