Adding MCP Servers to Claude Code

Direct answer: Add a local MCP server with claude mcp add <name> <command> [args...]. For a remote server, add --transport http or --transport sse before the name and provide its URL. Choose a configuration scope deliberately, then use claude mcp list, claude mcp get <name>, or /mcp to verify and authenticate the connection.

MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. In Claude Code, an MCP server exposes tools or data that Claude can call during a session. The setup guide and CLI reference are the authoritative references for current command behavior: Claude Code MCP setup and Claude Code CLI reference.

1. Decide which MCP setup you need

Question	Choice	When to use it
Where does the server run?	Local stdio	A command such as `npx`, Python, or another executable runs on your machine.
Where does the server run?	Remote HTTP or SSE	A hosted service exposes an MCP endpoint over the network.
Who receives the configuration?	`local`	Only you, in the current project; useful for private experiments and credentials.
Who receives the configuration?	`project`	The project shares a `.mcp.json` file with the team. Claude Code asks for approval before using these servers.
Who receives the configuration?	`user`	You can use the server across projects while keeping it in your user configuration.

If the same server name exists at more than one scope, precedence is local, then project, then user.

2. Add a local stdio MCP server

A stdio server is a local process that Claude Code starts and communicates with through standard input and output.

claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY -- npx -y airtable-mcp-server

The -- separator matters. Options before it belong to Claude Code; the command and arguments after it are passed to the MCP server.

Specify a scope

# Private to you and this project
claude mcp add --scope local my-server -- ./my-server --port 3000

# Shared through the project root's .mcp.json
claude mcp add --scope project my-server -- ./my-server

# Available to you in every project
claude mcp add --scope user my-server -- ./my-server

Use local for secrets or one-off testing. Use project when the team should receive the server definition. Use user for a personal integration you want everywhere.

Pass environment variables safely

claude mcp add --scope user payments \
  --env STRIPE_SECRET_KEY=YOUR_KEY \
  --env STRIPE_ACCOUNT=acct_example \
  -- python payments_mcp.py

Keep credentials in environment variables or your operating system’s secret store. Do not commit secrets to a project .mcp.json.

Windows command wrapper

On native Windows, an npx-based server may need the cmd /c wrapper:

claude mcp add my-server -- cmd /c npx -y @some/package

3. Add a remote MCP server

HTTP transport

claude mcp add --transport http notion https://mcp.notion.example/mcp

For a service that expects a bearer token, pass a header:

claude mcp add --transport http notion \
  https://mcp.notion.example/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

SSE transport

claude mcp add --transport sse linear https://mcp.linear.example/sse

Headers can be supplied for SSE services that require an API key:

claude mcp add --transport sse linear \
  https://mcp.linear.example/sse \
  --header "X-API-Key: YOUR_KEY"

Authenticate with OAuth

Add the HTTP or SSE server.
In Claude Code, run /mcp.
Select the server and complete its OAuth 2.0 login flow.

OAuth support applies to HTTP and SSE transports. The server controls the identity provider and requested permissions.

4. Configure a server with JSON

Use claude mcp add-json when you already have a JSON definition or need settings that are easier to review as data.

claude mcp add-json weather '{
  "command": "npx",
  "args": ["-y", "weather-mcp"],
  "env": {
    "WEATHER_API_KEY": "${WEATHER_API_KEY}"
  }
}'

In .mcp.json, variables can use ${VAR} or ${VAR:-default}. If a required variable has no value and no default, parsing fails. Expansion applies to commands, arguments, environment values, URLs, and headers.

Example project `.mcp.json`

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "docs-mcp"],
      "env": {
        "DOCS_TOKEN": "${DOCS_TOKEN}"
      }
    },
    "remote-search": {
      "transport": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SEARCH_TOKEN}"
      }
    }
  }
}

5. Verify, inspect, and remove servers

# List configured servers
claude mcp list

# Inspect one server
claude mcp get my-server

# Remove a server
claude mcp remove my-server

After adding a server, ask Claude to use one of its tools or open /mcp. If the server requires OAuth, /mcp is also where you complete sign-in.

6. Import Claude Desktop servers

If you already configured MCP servers in Claude Desktop, you can import selected entries:

claude mcp add-from-claude-desktop

This import command is documented for macOS and WSL.

7. Use Claude Code’s MCP configuration file option

The CLI also supports loading servers from JSON files or JSON strings with --mcp-config. This is useful in scripts or when you want to keep a separate configuration file for a session.

claude --mcp-config ./mcp.json

Keep the file readable only by the users who need its credentials, and use environment-variable expansion instead of hard-coding secrets.

8. Or skip the browser setup

If your MCP workflow needs website screenshots, ScreenshotNeo provides a screenshot API and an MCP server for AI agents such as Claude and Cursor. You can call the API directly while keeping Claude Code as the orchestration layer.

See the ScreenshotNeo API documentation for the current options and parameter names.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups and chat widgets are removed before the shot. Bot checks, blank pages, failed loads and cache hits are not billed, and response headers report the page verdict and billing status. The MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account.

9. Troubleshooting common errors

Symptom	Likely cause	Fix
Claude says the server is unavailable	The command is missing, not executable, or exits immediately.	Run the command manually, confirm its path, then inspect it with `claude mcp get <name>`.
Arguments are interpreted as Claude options	The command was not separated from CLI flags.	Insert `--` before the server command.
`npx` fails on Windows	Native Windows shell resolution prevents direct execution.	Use `cmd /c npx -y package-name`.
OAuth login never appears	The server was added with the wrong transport or the session has not opened the MCP panel.	Use HTTP or SSE as documented by the provider, then run `/mcp`.
JSON configuration will not parse	A required `${VAR}` is unset, or the JSON has invalid quoting.	Export the variable or provide `${VAR:-default}`; validate the JSON and retry.
The wrong server definition is used	The same name exists at multiple scopes.	Check each scope and remember precedence: local, project, user.
Startup takes too long	The process downloads dependencies or waits on a network service.	Install dependencies ahead of time, reduce startup work, or adjust `MCP_TIMEOUT`.
Tool output is truncated or warns about size	The response exceeds Claude Code’s output threshold.	Set `MAX_MCP_OUTPUT_TOKENS` to an appropriate value and have the server return focused results.

10. Performance, reliability, and security

Startup: Local servers that use package runners may spend time resolving or downloading dependencies. A stable installation and a short startup path reduce first-call latency.
Network reliability: Remote HTTP and SSE servers depend on DNS, TLS, authentication, and provider availability. Keep tool calls small and retry only operations that are safe to repeat.
Output size: Return structured, narrowly scoped data. Large tool responses consume context and can trigger the output warning threshold.
Scope: Project scope is convenient for teams, but review the committed .mcp.json and approve only servers you trust.
Credentials: Prefer environment variables, headers managed by the provider, or OAuth. Avoid placing API keys directly in shared JSON.
Cost: Claude Code’s MCP setup commands do not establish a universal MCP price; each remote provider sets its own terms. ScreenshotNeo’s free and paid screenshot plans are listed above and in its documentation.

11. Practical setup checklist

Identify whether the server is local stdio, remote HTTP, or remote SSE.
Choose local, project, or user scope.
Add the server and put -- before the server command for stdio.
Supply secrets through environment variables, headers, or OAuth.
Run claude mcp list and claude mcp get <name>.
Open /mcp when OAuth is required.
Invoke one tool and inspect the returned data before relying on the integration.

12. FAQ

Can one Claude Code project use several MCP servers?

Yes. Add each server with a unique name, or define several entries in .mcp.json.

Should a team server use project scope?

Use project scope when the configuration belongs in the repository and teammates should share it. Review the file and keep secrets outside it.

How do I change an existing server?

Inspect it with claude mcp get, remove it with claude mcp remove, and add it again with the corrected command or JSON.

Which transport should a hosted service use?

Use the transport the service documents: HTTP or SSE. Do not assume that a URL supporting one transport supports the other.

Can Claude Code connect to a screenshot service?

Yes. You can configure a screenshot provider as an MCP server when it publishes one, or call its HTTP API from a tool. ScreenshotNeo offers both an API and an MCP server.