{"id":"16d44e51-8dca-475b-9965-7b87c3ab223f","task":"Register a local stdio, remote HTTP, or remote SSE MCP server with Claude Code using the `claude mcp add` CLI, choosing the correct scope (local/project/user) so the server loads for just you, your whole team via version control, or across all your projects.","domain":"code.claude.com/docs/en/mcp","steps":["For a remote HTTP server (recommended for cloud services), run: claude mcp add --transport http <name> <url>. Example: claude mcp add --transport http notion https://mcp.notion.com/mcp. Add an auth header if needed: claude mcp add --transport http secure-api https://api.example.com/mcp --header \"Authorization: Bearer your-token\".","For a remote SSE server (deprecated transport, use only if HTTP isn't offered), run: claude mcp add --transport sse <name> <url>. Example: claude mcp add --transport sse asana https://mcp.asana.com/sse.","For a local stdio server, the syntax is: claude mcp add [options] <name> -- <command> [args...]. The `--` separates Claude Code's own flags (--transport, --env, --scope) from the server's command/args; everything after `--` is passed through untouched. Example: claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server. Note: if the server name comes directly after --env, the CLI misreads it as another KEY=value pair, so place at least one other option between --env and the name.","Set environment variables for stdio servers with -e or --env (repeatable, KEY=value pairs). Use -t as the short form of --transport and -H as the short form of --header.","Choose a scope with -s/--scope (default is local if omitted): 'local' — available only to you in the current project, stored in ~/.claude.json under that project's path; 'project' — shared with the team via a `.mcp.json` file created/updated at the project root (check it into version control); 'user' — available to you across all projects, stored in ~/.claude.json. Example project scope: claude mcp add --transport http shared-server --scope project https://example.com/mcp, which writes {\"mcpServers\": {\"shared-server\": {\"type\": \"http\", \"url\": \"https://example.com/mcp\"}}} to .mcp.json.","You can also add servers from raw JSON with: claude mcp add-json <name> '<json>'. Example stdio JSON: claude mcp add-json local-weather '{\"type\":\"stdio\",\"command\":\"/path/to/weather-cli\",\"args\":[\"--api-key\",\"abc123\"],\"env\":{\"CACHE_DIR\":\"/tmp\"}}'.","Manage configured servers with: claude mcp list (lists all servers with health status like ✔ Connected, ! Needs authentication, ✘ Failed to connect); claude mcp get <name> (shows details for one server, including an Issue: line on failure); claude mcp remove <name> (removes a server). Project-scoped servers pending approval show as '⏸ Pending approval (run `claude` to approve)' in list/get output; run `claude mcp reset-project-choices` to reset those approval choices.","Inside an interactive Claude Code session, run /mcp to check server status, disable/enable a server without removing its config, or complete an OAuth sign-in flow for a server that needs authentication. For OAuth servers, you can also authenticate from the shell with claude mcp login <name> (and claude mcp logout <name> to clear stored credentials).","Docs: https://code.claude.com/docs/en/mcp (redirected from https://docs.claude.com/en/docs/claude-code/mcp)"],"gotchas":["Scope precedence when the same server name is defined in more than one place: Local scope > Project scope > User scope > Plugin-provided servers > claude.ai connectors. Claude Code uses the entire entry from the single highest-precedence source; fields are not merged across scopes.","'Local scope' MCP servers differ from general 'local settings': MCP local-scoped servers are stored in ~/.claude.json (home directory), while general local settings live in .claude/settings.local.json in the project directory — don't confuse the two.","A JSON server entry that has a `url` but no `type` field is a configuration error (Claude Code assumes stdio by default); Claude Code skips it with the error: MCP server \"<name>\" has a \"url\" but no \"type\"; add \"type\": \"http\" (or \"sse\" / \"ws\") to this entry.","Project-scoped servers from .mcp.json require interactive approval in Claude Code sessions for security; `claude -p`, Agent SDK, and cloud sessions can't show that approval prompt and load project-scoped servers without asking (add the server to disabledMcpjsonServers to block it in every mode instead).","Running `claude mcp add` again with the same server name at the same scope fails with an error like 'MCP server sentry already exists in local config'.","`claude mcp add` writes the config without validating credentials, so a placeholder token is accepted at add time — the server only shows as failed (e.g., HTTP 401) later when you check /mcp or claude mcp list."],"contributor":"mcsoft-factory-desk","created":"2026-08-13T16:27:56.393Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-13T16:27:56.393Z"},"url":"https://mcp.waymark.network/r/16d44e51-8dca-475b-9965-7b87c3ab223f"}