Choose `claude mcp add` or `.mcp.json`
Use the CLI when you want Claude Code to write the correct structure for you. It reduces syntax mistakes and makes the chosen scope explicit. Use a hand-reviewed `.mcp.json` when a project needs a shared, versioned definition or when you are editing a pull request that introduces an integration.
A project-scoped file is code. Review the command, arguments, endpoint, headers, and requested privileges before approval. Claude Code prompts before using project-scoped servers, but that prompt is not a source or package audit.
Add a local stdio server or a remote HTTP server
For stdio, everything after `--` is passed to the server process. Put Claude options before the server name. For HTTP, provide the endpoint instead of a launch command. Use a harmless server while validating mechanics; a successful launch does not prove that a production package is trustworthy.
Local stdio server
claude mcp add --transport stdio --scope local demo -- npx -y example-mcp-serverRemote Streamable HTTP server
claude mcp add --transport http --scope local hosted https://example.com/mcpShare configuration without sharing secrets
Claude Code supports environment expansion in `command`, `args`, `env`, `url`, and `headers` inside `.mcp.json`. Commit the variable reference, not the token. A missing required variable without a default causes config parsing to fail, which is preferable to silently sending an empty credential.
Do not assume environment variables are automatically safe: they can still leak through logs, child processes, screenshots, or shell history. Use the least-privileged credential, keep it out of source control, and redact it from diagnostic bundles.
Shared HTTP definition with a private token
{
"mcpServers": {
"hosted": {
"type": "http",
"url": "${MCP_BASE_URL:-https://example.com}/mcp",
"headers": {
"Authorization": "Bearer ${MCP_TOKEN}"
}
}
}
}Verify the declaration, connection, and first tool separately
Run `claude mcp list` to check configured servers and health, then `claude mcp get <name>` to inspect one definition. Inside Claude Code, open `/mcp` and confirm the server and its tools are visible. Finally invoke one read-only or otherwise reversible tool and check the returned result.
Treat these as separate gates: the JSON can parse while the executable is missing; the process can start while discovery fails; tools can list while the upstream API rejects authorization. Record which gate failed before changing configuration.
Operational commands
claude mcp list
claude mcp get demo
claude mcp remove --scope local demo
claude mcp reset-project-choicesUse the failure tree instead of changing everything at once
If the executable is not found, test the exact command from the environment that launches Claude Code and prefer a stable absolute path only when necessary. If the endpoint returns 401 or 403, repair authentication rather than retrying. If the process stays alive but exposes zero tools, inspect the server's discovery output and stderr. Restart the client only after a config or environment change that requires it.
- Executable failure: command/PATH/permissions before package arguments.
- Connection failure: transport, URL, TLS, proxy, then authentication.
- Discovery failure: protocol compatibility, stderr, and tool/resource list responses.
- Tool failure: input schema, downstream credentials, rate limits, and handler logs.