Claude MCP Add Command: HTTP, stdio, scope, and authentication
Use the claude mcp add command for HTTP and stdio servers, choose the right scope, configure authentication, and verify your Claude Code setup.
Author: Variant Team. Variant is built by a small team working on HTML-native presentation tools, MCP workflows, and agent-editable decks.
The claude mcp add command connects Claude Code to an MCP server. The right syntax depends on one basic distinction: does the server run at a remote HTTP URL, or does Claude Code start it as a local process?
Scope is the second decision. Choosing the wrong scope is a common reason a working server seems to disappear.
#Quick answer
For a remote server, run claude mcp add --transport http <name> <url>. For a local stdio server, run claude mcp add <name> -- <command> [args]. Add --scope user for a personal server you want in every project, or --scope project for a server whose configuration should travel with the repository. The default scope is local.
#HTTP and stdio syntax
An HTTP server already runs somewhere else. Claude Code needs a name and URL:
claude mcp add --transport http example https://mcp.example.com/mcpA stdio server is a local command that Claude Code starts and communicates with through standard input and output. Put the executable and its arguments after --:
claude mcp add local-example -- node ./path/to/server.jsUse HTTP for a hosted service with a stable URL. Use stdio when the server is a local executable or part of the current development environment. If a server's documentation gives you a URL, do not convert it into a made-up package command.
#Flag reference
These are the claude mcp add options covered by the current Claude Code CLI.
| Flag | What it does | When to use it | ||
|---|---|---|---|---|
--transport http | Adds a remote HTTP MCP server. | When the provider gives you an MCP URL. | ||
| `-s, --scope <local | user | project>` | Selects where Claude Code saves the configuration. The default is local. | user for personal use across projects, or project for shared setup. |
-e, --env KEY=value | Passes an environment variable to a local process. | For stdio server settings or credentials. | ||
-H, --header "Header: value" | Sends an HTTP header to a remote server. | When the server requires a fixed header. | ||
--client-id <id> | Supplies an OAuth client ID. | Use it when the MCP provider requires a registered OAuth client. | ||
--client-secret | Supplies the corresponding OAuth client secret. | Use it only when the provider's OAuth setup requires a client secret. | ||
--callback-port <port> | Fixes the local port used for the OAuth callback. | When a registered redirect URI requires a specific port. |
Do not add authentication flags by guesswork. Start with the provider's documented command. Use claude mcp add --help to confirm syntax for the Claude Code version installed on your machine.
#Choose the right scope
The three scopes answer two questions: who should see the server, and in which projects?
| Scope | Who and where | Good default for |
|---|---|---|
local | You, in the current project | Testing a server or keeping a project-specific personal connection |
project | People who use the repository | Team servers with configuration that should be shared through the repo |
user | You, across projects | Personal accounts and services you use everywhere |
local is the command default. If you change directories and the server is missing, check whether you added it with local scope in another project.
A useful rule is simple: personal accounts go to user; team servers go to project.
Project scope needs extra care. Configuration shared through a repository can be committed. Never put a static secret directly into a project-scope header. A command such as -H "Authorization: Bearer secret-value" can expose that value to anyone with repository access if the generated configuration is committed.
#Authentication for HTTP servers
Many hosted HTTP MCP servers use OAuth. Add the server first, then let Claude Code start sign-in when it connects. A provider may also require --client-id, --client-secret, or --callback-port.
The callback port is not a general networking fix. It exists for an OAuth provider that accepts only a pre-registered redirect URI. In that case, the local callback must use the registered port. Leave the option out when the provider does not require it.
Some servers expect a static authorization header instead of OAuth. The shape is:
claude mcp add --transport http \
-H "Authorization: Bearer YOUR_TOKEN" \
example https://mcp.example.com/mcpOn zsh, quote the entire header as shown. Prefer OAuth when the server supports it because a literal header value is easy to leak.
For a presentation-specific setup guide, see Connect Claude Code to Variant over MCP.
#Check, list, and remove servers
After adding a server, inspect the exact entry:
claude mcp get exampleList all servers visible in the current context:
claude mcp listRemove an entry you no longer want:
claude mcp remove exampleUse the same server name in all four commands. If claude mcp get example cannot find the new entry, check the current directory and scope before changing the URL.
#Worked example with Variant
Variant exposes a hosted, streamable HTTP MCP endpoint. Add it with this exact command:
claude mcp add --transport http variant https://mcp.variant.art/mcpThen verify the entry:
claude mcp get variantVariant uses OAuth by default. The first MCP request opens a browser for sign-in. After authentication, try a prompt that gives Claude Code a clear artifact, audience, and size:
Create a five-slide product review deck in Variant for an engineering audience. Start with the problem, compare two implementation options, and end with a recommendation. Use concise copy and preview each slide before finishing.
Claude Code can use Variant's MCP tools such as deck.create, deck.replaceAllSlides, and slide.preview. The deck contains real HTML and CSS slides and opens in Variant for visual edits, comments, and export. Review the previews because a successful tool call does not prove the layout is finished.
If your team requires the final file in PowerPoint, Variant can export PPTX. It can also export single-file HTML, PDF, and JSON. The presentation MCP server documentation describes the wider workflow.
Variant is not the right choice when the deck must remain in Google Slides or you want a local presentation framework under full source control. Use Google Slides for the first case and Reveal.js for the second.
#Claude Code and Codex equivalents
| Task | Claude Code | Codex CLI |
|---|---|---|
| Add an HTTP server | claude mcp add --transport http <name> <url> | codex mcp add <name> --url <url> |
| Add a stdio server | claude mcp add <name> -- <command> [args] | codex mcp add <name> -- <command> [args] |
| Select scope while adding | --scope local, --scope user, or --scope project | No equivalent add flag in this reference |
| Pass a stdio environment value | --env KEY=value | --env KEY=VALUE |
| Send a static HTTP bearer token | --header "Authorization: Bearer ..." | --bearer-token-env-var <ENV_VAR> reads the token from an environment variable |
| Inspect one server | claude mcp get <name> | codex mcp get <name> |
| List servers | claude mcp list | codex mcp list |
| Remove a server | claude mcp remove <name> | codex mcp remove <name> |
| Start an explicit OAuth login | Connection starts the hosted server's OAuth flow | codex mcp login <name> |
For a full Codex walkthrough, read How to add an MCP server to Codex. The flags are not interchangeable.
#Troubleshooting
#The server is added but tools are missing
Run claude mcp get <name> and claude mcp list. Confirm the URL and transport, then complete OAuth sign-in if required. If the entry looks correct, restart the Claude Code session.
#The server exists in one project but not another
The entry was probably added with local scope. Use --scope user for a personal server across projects or --scope project for shared repository configuration.
#The authorization header breaks in zsh
Wrap the complete header in straight double quotes:
-H "Authorization: Bearer YOUR_TOKEN"Do not split the value into separate shell arguments. Follow the provider's recommended secret handling.
#OAuth returns a redirect URI error
Use --callback-port <port> only when the server provider has registered a redirect URI with that port. The port must match the provider's OAuth configuration. If no callback port is documented, do not invent one.
#Related reading
- How to add an MCP server to Codex
- What is an MCP server for presentations?
- Claude Code MCP setup
- Variant MCP tools
#FAQ
#What is the claude mcp add command for an HTTP server?
Run claude mcp add --transport http <name> <url>. Replace <name> with a short local name and <url> with the provider's documented MCP endpoint.
#How do I add a local stdio MCP server to Claude Code?
Run claude mcp add <name> -- <command> [args]. The -- separator marks the start of the local server command and its arguments.
#What is the default Claude MCP scope?
The default scope is local, which applies to you in the current project. Use user for a personal server across projects and project for configuration shared through a repository.
#How do I list MCP servers in Claude Code?
Run claude mcp list to list visible servers. Run claude mcp get <name> when you need to inspect one named entry.
#Should I put an authorization header in project scope?
Do not put a literal secret in a project-scope configuration that may be committed. Prefer the provider's OAuth flow or its documented method for keeping credentials outside shared configuration.
#When should I use the OAuth callback port?
Use --callback-port <port> when the MCP provider requires a pre-registered OAuth redirect URI on a specific local port. Leave it unset when the provider does not document that requirement.
#The short version
Use claude mcp add --transport http <name> <url> for hosted servers and claude mcp add <name> -- <command> [args] for local stdio servers. Choose user scope for personal accounts, project scope for team configuration, and the default local scope for project-specific personal setup. Verify every entry with claude mcp get <name> before debugging the server itself. Variant fits teams that want Claude Code to create editable HTML and CSS decks, but use the native destination or a local slide framework when that better matches the required workflow.
Next step
Connect Claude Code to Variant
Add Variant as an MCP server, then ask Claude Code to create or edit a real HTML slide deck.