Claude Code

The one-line add command, the three scopes and the file each writes, and the key as a header.

Claude Code stores MCP servers in three places, and the scope flag picks which. Local scope, the default, writes ~/.claude.json under the current project path. --scope project writes .mcp.json at the project root, which is the one you commit so the whole team gets the server. --scope user writes ~/.claude.json for every project you open.

Without a key

claude mcp add --transport http wellworn https://mcp.wellworn.dev/mcp

Add -s project to put it in .mcp.json instead:

claude mcp add --transport http wellworn https://mcp.wellworn.dev/mcp -s project

The JSON that command writes uses "type": "http", which is the field name to copy if you are editing .mcp.json by hand:

.mcp.json

{
  "mcpServers": {
    "wellworn": {
      "type": "http",
      "url": "https://mcp.wellworn.dev/mcp"
    }
  }
}

With a key

A key is one header. Re-running add with the header replaces the entry, so this is also how you rotate.

claude mcp add --transport http wellworn https://mcp.wellworn.dev/mcp \
  --header "Authorization: Bearer ww_your_key"

.mcp.json is committed more often than not, so in project scope expand an environment variable rather than pasting the key. Claude Code substitutes ${VAR} in header values at connect time, and ${VAR:-default} falls back when the variable is unset.

.mcp.json

{
  "mcpServers": {
    "wellworn": {
      "type": "http",
      "url": "https://mcp.wellworn.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${WELLWORN_KEY}"
      }
    }
  }
}

Confirm it works

claude mcp list prints every configured server with a health mark next to it: ✔ Connected, ! Needs authentication, or ✘ Failed to connect. Inside a session, /mcp opens the panel with each server's tool count. Wellworn should show eight: recommend, compare, alternatives, traps, skill, design, docs, submit_trap.

What breaks

If a referenced environment variable is not set and has no default, Claude Code connects with the literal ${VAR} text in the header and warns instead of failing, so the server appears configured while every call falls back to the anonymous tier. Check claude mcp get wellworn when calls start hitting the 60-a-day cap sooner than the key's allowance would explain.

The CLI flag is --transport http. The MCP specification's own name for this transport, streamable-http, is accepted in JSON but rejected as a CLI flag value.

Verified 2026-09-08 against code.claude.com

The plugin

The server answers when the agent asks. The plugin makes it ask on its own, on package installs and dependency-manifest edits. It is documented on the Claude Code plugin page.

claude plugin marketplace add WellWorn-dev/wellworn
claude plugin install wellworn@wellworn

Verified 2026-09-08 against code.claude.com

Removing it

claude mcp remove wellworn