From a62321eb4a741df70fd5944c9178e02192272b6d Mon Sep 17 00:00:00 2001 From: MechaCat02 Date: Sat, 12 Sep 2026 22:10:41 +0200 Subject: [PATCH] docs: register MCP servers at user scope, not the default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/LOCAL.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/LOCAL.md b/docs/LOCAL.md index 40cf515..16c6135 100644 --- a/docs/LOCAL.md +++ b/docs/LOCAL.md @@ -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.