sdl-mcp init generates invalid Claude Code config — mcpServers belongs in .mcp.json, not settings.json

[timoburmeister]

Summary

Running sdl-mcp init on a Claude Code project auto-detects the claude-code MCP client and generates a config block — but it targets the wrong file. The generated config puts mcpServers inside .claude/settings.json, which Claude Code's schema explicitly rejects. This silently breaks the MCP server for every Claude Code user who follows the auto-generated output.

---

Environment

• sdl-mcp: 0.10.5
• Node.js: v24.15.0
• Platform: macOS (darwin x64)
• MCP client: Claude Code (CLI)

---

What sdl-mcp init generates

Running sdl-mcp init -y in a project with a .claude/ directory produces:

Detected MCP clients and config blocks:
- claude-code: .claude/settings.json
{
  "mcpServers": {
    "sdl-mcp": {
      "command": "npx",
      "args": ["--yes", "sdl-mcp@latest", "serve", "--stdio"],
      "env": {
        "SDL_CONFIG": "/Users/.../.config/sdl-mcp/sdlmcp.config.json"
      }
    }
  }
}

It also does not write this config automatically — it only prints it. A user following these instructions will add it to .claude/settings.json and get:

Claude Code settings.json validation failed after edit:
Settings validation failed:
- : Unrecognized field: mcpServers. Check for typos or refer to the documentation for valid fields.

---

Root Cause

Claude Code uses two separate config files with different schemas:

File	Purpose
.claude/settings.json	Claude Code behaviour settings (permissions, env vars, hooks, etc.)
.mcp.json	Project-level MCP server definitions

The mcpServers key is only valid in .mcp.json. Additionally, sdl-mcp init detects the claude-code client correctly but neither writes the config
automatically nor points to the right file.

---

Correct Config

The working setup requires two files:

.mcp.json (create at project root):

{
  "mcpServers": {
    "sdl-mcp": {
      "command": "npx",
      "args": ["--yes", "sdl-mcp@latest", "serve", "--stdio"],
      "env": {
        "SDL_CONFIG": "/Users/<you>/.config/sdl-mcp/sdlmcp.config.json"
      }
    }
  }
}

.claude/settings.json (add to existing file):

{
  "enabledMcpjsonServers": ["sdl-mcp"]
}

The enabledMcpjsonServers field is required — without it, Claude Code prompts for approval on every session start.

---

Additional Installation Friction

1. Node.js 24 minimum not prominently documented

Installation fails silently or with cryptic errors on Node 22. The README should prominently state node >= 24 is required. A clear startup error would also
help: sdl-mcp requires Node.js 24+, found v22.x.

2. Noisy peer dependency warnings during npm install -g sdl-mcp

The global install produces ~15 ERESOLVE overriding peer dependency warnings from tree-sitter grammar packages conflicting on their tree-sitter peer version.
These are alarming and suggest a broken install even though it succeeds. Pinning the tree-sitter grammars to a consistent peer-compatible version range would
reduce friction.

---

Suggested Fix

In the sdl-mcp init claude-code detection path:

1. Write to .mcp.json (not .claude/settings.json)
2. Optionally add "enabledMcpjsonServers": ["sdl-mcp"] to .claude/settings.json
3. Update the printed instructions to reference .mcp.json

[GlitterKill]

Will address. Thanks.

[GlitterKill]

You can also use the main .claude.json config to setup the server (that is the way I did it). I will add it as an init or install step that asks if you want to install for the project only (your provided use case) or as a global user install (the way I installed it).