AI how-to notes · 2026-09-17 · last run 2026-09-17 · 한국어 원문

Adding an MCP server to Claude Code on Windows — a minimal claude mcp add --scope project setup and clearing Pending approval

The short version

On Windows PowerShell, claude mcp add name --scope project -- npx -y package args writes a .mcp.json into the project folder. On our setup (2.1.274) the server connected without wrapping npx in cmd /c, and it showed as ⏸ Pending approval until approved.

In this run, an unapproved project server appeared as ⏸ Pending approval in both claude mcp list and get. Step 2 brings together the documented interactive trust and approval path and the single-invocation --settings example we actually ran.

2026-09-28 documentation review and reorganization: we reread the approval guidance in the MCP docs and quickstart. The Windows measurements and output below remain from 2026-09-17; this is not a new interactive approval test or Windows rerun.

Who this is for

You followed a tutorial, ran claude mcp add, and claude mcp list shows nothing but Pending approval. Or you want to know whether cmd /c is needed to attach an npx server on Windows. Or you want a server in one project only, without touching your user settings file.

What we tested on

Pick the scope first

The scope option from claude mcp add --help:

  -s, --scope <scope>          Configuration scope (local, user, or project)
                               (default: "local")

The default of local matters. The table in the official docs (code.claude.com/docs/en/mcp, checked 2026-09-17) shows that local and user both save to ~/.claude.json, and only project saves to .mcp.json in project root. The quickstart page (code.claude.com/docs/en/mcp-quickstart, checked the same day) notes that on Windows ~/.claude.json is %USERPROFILE%\.claude.json. To leave our personal settings file untouched, we used --scope project exclusively.

Step 1 — add it

Set-Location 'C:\Users\User\AppData\Local\Temp\longtail_C\proj'
claude mcp add tempfs --scope project -- npx -y @modelcontextprotocol/server-filesystem 'C:\Users\User\AppData\Local\Temp\longtail_C\proj'

Added stdio MCP server tempfs with command: npx -y @modelcontextprotocol/server-filesystem C:\Users\User\AppData\Local\Temp\longtail_C\proj to project config
File modified: C:\Users\User\AppData\Local\Temp\longtail_C\proj\.mcp.json

Everything after -- is the command that launches the server. The docs put it as "Everything after -- is passed to the server untouched." Here is the .mcp.json it produced. Backslashes in a Windows path get doubled inside JSON.

{
  "mcpServers": {
    "tempfs": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\User\\AppData\\Local\\Temp\\longtail_C\\proj"
      ],
      "env": {}
    }
  }
}

Step 2 — check the status, and meet Pending approval

$ claude mcp get tempfs
tempfs:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: stdio
  Command: npx
  Args: -y @modelcontextprotocol/server-filesystem C:\Users\User\AppData\Local\Temp\longtail_C\proj

claude mcp list showed the same status. The help text says "Unapproved .mcp.json servers are shown as ⏸ Pending approval and not connected to", so no connection is even attempted.

The official guidance (rechecked 2026-09-28) is to run the command below in the same project folder, then review and accept the workspace trust dialog and project-server approval request when they appear. We did not test this interactive path in the original run.

claude

The path we actually tested is the --settings command below. It applies approval to that invocation without opening a chat session or saving the value to a settings file. enableAllProjectMcpServers approves every server in that .mcp.json; our test file contained only tempfs.

claude --settings '{"enableAllProjectMcpServers": true}' mcp get tempfs

tempfs:
  Scope: Project config (shared via .mcp.json)
  Status: ✔ Connected
  Type: stdio
  Command: npx

✔ Connected came back with npx exactly as configured, no cmd /c wrapper. The 2026-09-17 search of the seven official doc pages we used (mcp, mcp-quickstart, setup, troubleshooting, troubleshoot-install, settings, settings-reference) for cmd /c also turned up zero hits.

Putting "enableAllProjectMcpServers": true into the project's .claude/settings.json had no effect in this folder (it stayed at Pending approval). That matches the documented behavior that in an untrusted folder the shared settings' project-server approval is ignored. The disabledMcpjsonServers rejection in the same file, however, did apply. The file-by-file comparison is written up separately in Claude Code settings precedence and the MCP approval test.

Step 3 — remove it

$ claude mcp remove tempfs --scope project
Removed MCP server tempfs from project config
File modified: C:\Users\User\AppData\Local\Temp\longtail_C\proj\.mcp.json

After removal the .mcp.json file stays, emptied down to {"mcpServers": {}}. The tempfs line disappeared from claude mcp list as well. Afterwards we counted occurrences of the strings longtail_C and tempfs in %USERPROFILE%\.claude.json and got zero for both (we counted only; we never opened the contents).

Results

Two things worth knowing

When we captured the output of claude mcp list into a PowerShell variable and printed it again, ⏸ came out as ??. Setting both [Console]::OutputEncoding and $OutputEncoding to [Text.Encoding]::UTF8 fixed it. The quickstart docs also mention that older consoles, such as the default Windows 10 console, may show √ and × in place of ✔ and ✘.

claude mcp list may cover servers from other scopes, not just this folder's. It does not connect to unapproved, rejected, or disabled servers, and the help text and docs state that WebSocket servers do not appear in the list. On our machine, after the experiment, a few processes from another server (the mcp-remote family) were still running with no parent process. We could not determine whether this health check spawned them. If the first run is slow, you can raise the MCP_TIMEOUT environment variable the docs mention (milliseconds, 30 seconds by default).

The Claude Code session we did this work in started with a notice reading gemini (CONNECTION_CLOSED): "Connection closed". We did not investigate the cause, nor whether it had anything to do with this tempfs experiment.

What didn't work

We could not fully delete the test folder. Every file went, but the empty proj folder remained, "being used by another process". The most recently started processes at that moment were from the mcp-remote family (their parent had already exited), and we left them running. We could not confirm whether those processes came from claude mcp list/get, or whether they were the ones holding the folder.

What we did not check

• The approval dialog and the /mcp screen in an interactive claude.
• What local and user scope additions look like inside ~/.claude.json (skipped to protect personal settings).
• Actually calling a tool (reading a file, and so on). We stopped at the connection status.
• Behavior when wrapped in cmd /c, and typing this into Command Prompt (cmd.exe).
• claude mcp add-json, and HTTP transport servers.
• The cause of the CONNECTION_CLOSED session notice.

See also

• Claude Code settings precedence and the MCP approval test
• Verifying a Claude Code native install on Windows