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:
2026-09-12 22:10:41 +02:00
parent e4d087682d
commit a62321eb4a

View File

@@ -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.