Claude Code MCP Server Configuration (2026): Setup, JSON Examples & Troubleshooting

Claude Code MCP Configuration: Quick Command Reference

If you already have Claude Code installed and want to connect your first MCP server, these are the most important commands to know.

Important: The claude mcp ... commands run in your operating system's terminal. The /mcp command runs inside an active Claude Code session.

Three useful MCP setup examples

Remote HTTP server — official Claude Code documentation:

Local stdio server — Playwright browser integration:

Remote HTTP server shared with your project:

These are three alternative examples. Don't register the same server multiple times under different scopes unless you understand how Claude Code handles overlapping configurations.

The first command is the easiest place to start because Anthropic's official documentation MCP server does not require account authentication.

What Is an MCP Server in Claude Code?

An MCP server is an application that exposes tools, data resources, or reusable prompts to an AI client through the Model Context Protocol.

Claude Code acts as an MCP host. It connects to MCP servers and makes their supported capabilities available during coding sessions.

For example, a GitHub MCP server can expose repository and pull-request operations, while a browser MCP server can provide tools for navigating websites and inspecting page behavior.

How MCP works

The basic interaction follows this sequence:

1. Claude Code connects to a configured MCP server.

2. The server reports its supported capabilities.

3. Claude discovers the available tools or resources.

4. A relevant user request may lead Claude to select a tool.

5. Claude Code sends the tool call to the server.

6. The server performs the requested operation and returns a result.

7. Claude uses the result to continue the task.

The MCP server performs its actions according to its own permissions and implementation. Connecting to a server does not automatically make every action safe.

MCP tools, resources, and prompts

Not every server exposes all three capabilities.

Some provide only a small set of tools. Others expose a more extensive integration with external systems.

Step 1: Check the Requirements Before Adding an MCP Server

Before configuring a server, verify that the environment is ready.

MCP setup prerequisites

• Claude Code is installed and can start successfully.

• You have authenticated with an eligible Claude account or supported provider.

• You know whether the server is hosted remotely or runs locally.

• You have the official server URL or executable command.

• You have any required account permissions.

• Your network allows the relevant connection.

• You understand what data and actions the server will access.

Check the installed Claude Code version:

Open a project directory before adding a local-scoped server.

If you have not installed Claude Code yet, complete the installation first. MCP configuration should not be used to troubleshoot a missing Claude Code executable.

Do you need Node.js for MCP?

Not for every server.

Remote HTTP MCP servers normally don't require you to install Node.js simply to connect to them.

Local servers started through npx do require Node.js and npm tooling. Other local servers may use Python, uvx, a standalone executable, or another supported runtime.

This distinction is important:

Claude Code's native installer may not need Node.js, but a particular local MCP server still might.

Step 2: Connect Your First Remote HTTP MCP Server

The most reliable beginner exercise is connecting to Anthropic's official Claude Code documentation server.

It is a real hosted MCP endpoint and does not require a separate API key.

Add the documentation server

Open your terminal inside a project directory.

Run:

The command registers the server at local scope by default.

Claude Code should display a confirmation indicating that the configuration was added.

What each part means

The server name is a label. You could choose another valid name, but using a clear descriptive name makes later troubleshooting easier.

Verify the connection

Run:

Find the claude-code-docs entry.

For a healthy connection, the status should indicate that the server is connected.

You can also inspect the specific server:

Test the connection inside Claude Code

Start an interactive session:

Then enter:

If the integration works, Claude should use a tool associated with the documentation server to retrieve the relevant information.

Why this is a useful test: It confirms more than the presence of a configuration file. It checks whether the MCP server is actually available during a Claude Code session.

Important: Added does not mean connected

The command may successfully save a server whose URL is unavailable or whose authentication is incorrect.

Always verify the connection separately.

Step 3: Understand MCP Transport Types

Claude Code supports multiple ways to communicate with MCP servers.

The transport determines whether Claude launches a local process, connects to a remote service, or maintains another supported connection type.

Claude Code MCP transport comparison

Remote HTTP: the preferred option for cloud services

Anthropic currently recommends HTTP for remote MCP servers.

A basic remote configuration looks like:

Use the actual endpoint supplied by the provider rather than guessing a path such as /mcp.

Local stdio: best for a local executable

A local MCP server runs as a process on your computer.

For example:

This is a command-shape example, not a complete working server. The file /path/to/server.py must exist and implement a compatible MCP server before the connection can succeed.

The -- separator is significant. It separates Claude Code's MCP configuration options from the command and arguments used to start the local server.

SSE: legacy transport

SSE support remains available for services that require it.

However, SSE is deprecated in Anthropic's current MCP guidance.

For a newly developed remote MCP service, choose HTTP unless the server provider specifies another appropriate transport.

Recent Claude Code versions can also attempt HTTP first and fall back to SSE for compatible endpoints. Older versions may require an explicit --transport sse configuration.

WebSocket: specialized remote transport

Claude Code also supports WebSocket MCP configuration for servers that use a persistent bidirectional connection.

Unlike HTTP and stdio, WebSocket configurations are added through JSON rather than through a --transport ws option.

For ordinary documentation, issue-tracker, and repository integrations, HTTP is usually the simpler choice.

Step 4: Add a Local MCP Server with Playwright

A local MCP server can give Claude access to an application or tool running on your machine.

A useful example is the Playwright MCP server, which allows an AI assistant to interact with a browser through supported browser automation tools.

This example uses the Playwright MCP package and is based on Anthropic's official MCP quickstart.

Requirements

Install Node.js and npm so that npx is available.

Confirm:

The Playwright MCP quickstart currently specifies Node.js 18 or later for this server. Your own project's runtime requirements may be different.

Register the Playwright server

The command registers a local stdio server and instructs Claude Code to launch the Playwright package using npx.

The -y option lets npx proceed without an interactive installation confirmation.

Verify the server

The first attempt can take additional time because the package may need to be downloaded.

If the server fails to connect, check that Node.js and npm work, review the server details, and inspect the relevant logs.

Do not continually reinstall packages without first identifying the failure.

Test the browser integration

Start Claude Code:

Ask:

The example website is a public demonstration page.

If the connection works, Claude Code should display the corresponding Playwright tool calls.

When Playwright MCP is useful

• Checking whether a marketing website renders correctly.

• Investigating responsive navigation behavior.

• Reproducing simple browser-based bugs.

• Reviewing a local development server.

• Testing an interface with explicit instructions and permissions.

Browser automation can interact with pages and potentially sensitive sessions. Use a safe environment and review any action that could modify data.

Step 5: Configure Claude Code MCP Servers Using .mcp.json

The CLI is convenient, but project teams often prefer configuration files that can be reviewed and version-controlled.

Claude Code supports an .mcp.json file in the project root.

Example project structure

Unlike hook registrations, MCP server entries for a shared project belong in .mcp.json, not automatically inside .claude/settings.json.

Complete project-level MCP configuration example

Save the following as .mcp.json:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]

This declares two MCP servers:

• claude-code-docs connects to an official hosted HTTP endpoint.

• playwright launches a local process using npx.

The file is valid JSON and uses the configuration structure described in Anthropic's MCP quickstart.

How to apply the configuration

1. Save .mcp.json in the project root.

2. Start Claude Code inside that project.

3. Review the server approval prompt.

4. Approve only configurations you trust.

5. Run /mcp inside Claude Code.

6. Confirm that the intended servers connect.

7. Test an appropriate tool call.

Do not publish secrets in .mcp.json

A project-level .mcp.json file may be committed to Git.

Do not include actual API keys, bearer tokens, database passwords, or private credentials.

Use supported environment-variable references or a secure authentication mechanism instead.

Also review an .mcp.json file before trusting an unfamiliar repository. A malicious local server entry can attempt to start an executable when the configuration is approved.

Step 6: Understand Local, Project, and User MCP Scopes

Claude Code supports three MCP configuration scopes.

These are easy to confuse with the settings scopes used for hooks.

MCP configuration scope comparison

Local is the default scope for claude mcp add.

This does not mean the configuration is stored in .claude/settings.local.json. MCP local settings are stored under the relevant project entry in your user's .claude.json file.

Example: Add an MCP server for every personal project

Use user scope for a trusted integration you regularly need across multiple projects.

Example: Add an MCP server for the whole team

This creates or updates .mcp.json in the project root.

Your team can review and commit the configuration so developers use the same server definition.

Avoid registering the same server multiple times

If a server name is used at multiple scopes, Claude Code follows its documented configuration precedence.

For normal local/project/user entries, the order is:

1. Local.

2. Project.

3. User.

Additional plugin, connector, and managed configurations have their own precedence rules.

Claude Code uses the highest-precedence matching server entry rather than merging fields from several definitions.

If an expected configuration is ignored, check whether a higher-precedence entry has the same server name.

Changing server scope

A server's scope is selected when it is added.

To change scope, remove the existing entry from the appropriate scope and register it again with the new scope.

For example:

Then:

Check your actual configuration before removing anything, especially if a team manages the server.

Step 7: Add MCP Configuration with claude mcp add-json

Sometimes a server provider gives you an mcpServers JSON block rather than a CLI command.

Claude Code can register an individual server configuration using claude mcp add-json.

Example: Add a remote HTTP server from JSON

This example uses POSIX shell quoting, suitable for Bash or Zsh.

PowerShell and CMD have different quoting behavior. For Windows, editing .mcp.json directly may be easier than adapting complex quoted JSON command arguments.

Example: Local stdio server entry

A local MCP entry generally includes a command and argument list:

{
  "type": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "@playwright/mcp@latest"
  ]

{
  "type": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "@playwright/mcp@latest"
  ]

{
  "type": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "@playwright/mcp@latest"
  ]

This is the individual server object that claude mcp add-json expects.

A complete .mcp.json file, by contrast, wraps one or more such objects inside mcpServers.

Common JSON configuration mistakes

For manual JSON changes, restart or reload the relevant session as needed and check the resulting connection.

Step 8: Configure GitHub MCP with Claude Code

GitHub is a practical MCP use case because software development often depends on issues, pull requests, discussions, and repository metadata.

Anthropic's current documentation describes connecting to GitHub's remote MCP endpoint using a personal access token.

What GitHub MCP can help with

Depending on server capabilities and token permissions, Claude Code may be able to:

• Read repository issues.

• Inspect pull requests.

• Find repository information.

• Review code-related discussions.

• Assist with issue triage.

• Perform permitted write actions when explicitly requested.

GitHub remote MCP endpoint

The documented GitHub MCP endpoint is:

Create a fine-grained GitHub token with access only to the repositories and permissions you need.

For example, read-only repository access is preferable when your task is simply inspecting code and issues.

Recommended approach: Keep the token out of the repository

A project-level configuration can reference a dedicated environment variable:

Set GITHUB_MCP_TOKEN in your own trusted environment or use an appropriate secure credential-management method.

Do not commit the token value to version control.

Verify authentication

After configuring the server:

If GitHub reports an authentication error, verify that:

1. Your token has not expired or been revoked.

2. The token belongs to the correct account.

3. The selected repositories are accessible to that token.

4. The required permissions are granted.

5. The environment variable is actually available to the Claude Code process.

6. The remote endpoint is reachable.

Test a read-only GitHub task

Inside Claude Code:

Only use repository names and permissions you are authorized to access.

Security recommendation: Give the server the minimum permissions required for the task. Avoid broad administrative tokens or unnecessary write access.

Step 9: Authenticate Remote MCP Servers with OAuth

Some hosted MCP servers use OAuth instead of requiring you to configure a static token manually.

This is common for SaaS services and other cloud integrations.

Example: Connect to Sentry

Anthropic's official MCP quickstart uses Sentry as an OAuth example.

Register the server:

Check the status:

A server requiring authentication may appear as:

Complete the OAuth login

Start Claude Code:

Inside the session:

Select the sentry server and choose the authentication option.

Complete the provider's browser-based authorization flow.

Return to Claude Code and verify that the connection is active.

What if the browser doesn't open?

Check:

• Your local browser and operating-system settings.

• Network restrictions or VPN requirements.

• Whether the authorization page is blocked.

• Whether the server supports the expected OAuth flow.

• Whether your organization's security policies require additional approval.

A 401 Unauthorized or 403 Forbidden response can indicate an authentication or authorization problem, but the specific meaning depends on the server and authentication method.

Static tokens vs. OAuth

Do not treat a connection as secure merely because it uses HTTPS. HTTPS protects transport, but the credentials, server behavior, requested permissions, and data handling still matter.

Step 10: Use Environment Variables Safely in MCP Configuration

Environment variables help keep machine-specific values and tokens out of a shared configuration file.

Claude Code supports variable expansion in project-level .mcp.json configurations.

Supported syntax

Example configuration

This example is a configuration pattern. It requires a real MCP-compatible endpoint and valid credentials supplied outside the file.

What happens if a variable is missing?

The current Claude Code reference documents missing-variable warnings for many configuration fields.

However, some sensitive environment-variable names are deliberately prevented from expanding into remote server URLs and headers.

For example, Claude Code's own authentication credentials should not be repurposed automatically for an unrelated MCP server.

Use server-specific credentials rather than forwarding your Anthropic API key to third-party services.

Avoid exposing secrets through command history

Directly pasting long-lived tokens into terminal commands can leave them in shell history or configuration files.

Prefer OAuth or a secure credential store where available.

If an integration requires an API key, use a dedicated credential with the minimum necessary scope and a clear rotation procedure.

Step 11: Troubleshoot Claude Code MCP Connection Errors

When an MCP server fails, determine whether the problem is configuration, network connectivity, authentication, process startup, or tool discovery.

Don't assume every error is caused by Claude Code itself.

MCP connection troubleshooting matrix

Diagnostic sequence

First: Confirm the server exists.

Second: Inspect the selected configuration.

Replace claude-code-docs with the server that is failing.

Third: Open the MCP panel.

Inside Claude Code:

Review the server status, available tools, and any authentication or approval action.

Fourth: Check the actual executable or URL.

For a local server, run the startup command manually only after reviewing what it executes.

For a remote server, confirm the endpoint against the provider's documentation.

Fifth: Inspect debug output.

Start a diagnostic Claude Code session using the documented debug options.

For example:

Review the generated diagnostics while protecting any sensitive information they might contain.

How to interpret a successful add operation

A confirmation such as:

means the configuration was registered.

It does not prove that the server's tools are reachable, its credentials are valid, or its operations work.

A proper setup test includes configuration, connection, authentication when needed, and at least one safe tool call.

Step 12: Fix MCP Servers That Won't Start on Windows

Windows users sometimes encounter issues when local MCP servers rely on commands installed through Node.js or another runtime.

Check the command first

Open PowerShell:

If npx is unavailable, fix the Node.js installation or PATH before troubleshooting the MCP configuration.

Verify which executable is available

If Windows reports multiple versions, confirm which installation is being used.

Check your shell environment

Claude Code can run natively on Windows, but a local MCP server may depend on a particular executable or shell behavior.

Some older instructions assume a Unix-like Bash environment, even when the package can be launched differently on Windows.

Use the startup command documented for the MCP server and your operating system.

Do not assume that every Bash command works unchanged inside PowerShell.

Check the correct configuration file

On Windows, the user configuration file is normally under your user profile:

%USERPROFILE%\.

%USERPROFILE%\.

%USERPROFILE%\.

Project-scoped configuration remains:

<project-root>\.

<project-root>\.

<project-root>\.

If you installed a local server inside WSL, its executable and runtime may exist only inside that Linux environment.

Use the Claude Code environment where the server's dependencies are actually installed.

Step 13: How to Remove or Disable an MCP Server

You don't need to keep every experimental integration enabled permanently.

Unused MCP servers can increase configuration complexity and, depending on how tools are exposed, consume context or introduce unnecessary access.

List existing servers

Remove a server

For the documentation example:

If the server exists under a specific scope, use the appropriate --scope option.

Removing a remote server can also remove the locally stored OAuth registration and tokens associated with that connection.

Disable without permanently removing

Claude Code also provides controls for disabling supported servers in a project.

Use /mcp to inspect the server and its available management options.

Disabling can be preferable when you occasionally use a tool but don't want it active for every development session.

What if a server still appears?

Check for:

• A duplicate server at another scope.

• A project-level .mcp.json entry.

• A user-scoped configuration.

• A plugin-provided MCP server.

• A connector associated with your Claude account.

• Organization-managed configuration.

Removing one registration does not necessarily remove a separate connection delivered through another integration.

Step 14: MCP Security and Permission Best Practices

MCP can give Claude access to repositories, databases, browser sessions, external APIs, and business systems.

This is useful, but every server adds another trust boundary.

Review the server before installation

Check who maintains the server and whether its source or documentation is trustworthy.

A server installed through npx may download and execute package code.

Use trusted packages, review permissions, and consider pinned package versions for production environments instead of always selecting the latest release.

Follow least-privilege access

Use a read-only database account for analytical tasks.

Give GitHub integrations access only to the repositories they need.

Avoid connecting production systems with administrative credentials when a limited account can complete the task.

Understand prompt injection risk

An MCP server may retrieve information from an issue tracker, document, repository, or website.

That external content can contain instructions or malicious text intended to influence an AI assistant.

Treat retrieved content as untrusted input. Do not assume that a connected service's output is automatically safe to follow.

Protect sensitive information

Review whether a server can access:

• Environment files.

• API keys and secrets.

• Private repositories.

• Customer information.

• Production databases.

• Browser sessions.

• Internal documents.

Do not expose sensitive data merely to make an integration easier.

Require review for important write actions

An MCP server might be able to change a repository, create an issue, update a database, or trigger an external workflow.

For important business operations, confirm the requested action, permissions, and intended result before execution.

Don't confuse MCP permissions with Claude Code hooks

Hooks can respond to lifecycle events, including certain tool calls.

MCP exposes external capabilities.

A hook may help validate a workflow, but it does not replace proper access controls on the MCP server or the systems that server connects to.

Step 15: Practical MCP Setup for a SaaS Web Development Team

Consider a small SaaS development team working on a marketing website and supporting application.

The team uses Claude Code for coding, debugging and documentation.

A useful MCP setup might look like this:

Workflow example: Investigate a website bug

The developer asks Claude Code to:

1. Read the relevant issue through the authorized issue-tracker integration.

2. Inspect the appropriate source files.

3. Use the browser tool to reproduce the problem in a test environment.

4. Suggest a correction.

5. Explain which files would need to change.

6. Request approval before making meaningful changes.

7. Run the project's relevant tests.

8. Summarize the result.

This workflow demonstrates how MCP can reduce manual copying between systems.

It does not require granting full administrative access to every connected service.

When should you add more servers?

Add a server when it removes a specific repeated problem.

A focused setup with two or three trusted MCP servers may be better than a large collection of integrations you rarely use.

Review tool availability, context consumption, credentials, and whether the connected services remain useful.

Claude Code MCP Configuration Checklist

Before treating your MCP configuration as complete, verify the following:

• Claude Code is installed and authenticated.

• The server's official documentation has been reviewed.

• The correct transport has been selected.

• The endpoint or startup command is accurate.

• Local runtime dependencies are installed where needed.

• The desired local, project, or user scope is selected.

• The configuration contains valid JSON where applicable.

• Secrets are excluded from shared repository files.

• Required environment variables are available.

• claude mcp list shows the intended server.

• Authentication or project approval is complete.

• /mcp shows the expected connection status.

• A safe tool call completes successfully.

• Requested permissions are appropriate.

• Troubleshooting information is documented.

• Unused or outdated integrations have been removed or disabled.

Common Claude Code MCP Configuration Mistakes

Confusing MCP with Claude Code installation

The Claude Code CLI must be installed before you can run its MCP management commands.

A missing claude command is an installation problem, not an MCP server problem.

Using an HTTP URL without declaring its transport

A JSON configuration with a url but no valid type can be interpreted incorrectly.

Use "type": "http" for an HTTP server entry.

Omitting the double-dash separator for local commands

For local stdio servers, -- separates Claude's MCP options from the server's startup command.

Without it, arguments intended for the server may be parsed incorrectly.

Assuming added means connected

A server can be saved successfully but fail because of missing credentials, runtime dependencies, an invalid endpoint, or a network restriction.

Always test the connection.

Putting secrets inside a shared configuration file

A team-scoped .mcp.json may be committed to source control.

Store actual credentials separately.

Confusing local scope with project scope

Local scope means private to you in the current project.

Project scope means shared through the project's .mcp.json configuration.

Installing untrusted servers without reviewing them

Local MCP servers can execute programs, while remote servers may receive sensitive context and perform external actions.

Review the server before giving it access.

Using deprecated SSE by default

SSE remains relevant for legacy servers, but HTTP is the recommended remote transport for new configurations.

Connecting too many tools at once

Excessive integrations can make troubleshooting, access reviews, and tool selection harder.

Start with the tools your workflow genuinely requires.

Final Recommendation: Start with One Trusted MCP Server

Claude Code MCP configuration becomes much easier when you begin with a simple verified server.

Start with Anthropic's documentation server, confirm that it connects, and use a read-only test prompt.

Then learn the difference between HTTP and stdio, choose the correct configuration scope, and move to local developer tools or authenticated integrations.

When sharing configuration with a team, use a reviewed .mcp.json file without embedded secrets.

For sensitive systems, restrict permissions and test the connection in a safe environment before introducing it into a production workflow.

The goal of MCP is not to connect Claude Code to every available service. It is to connect the right tools, with the right permissions, so developers can complete useful work more reliably.

Official Documentation and Sources

• Anthropic — Claude Code MCP Quickstart

• Anthropic — Complete Claude Code MCP Reference

• Model Context Protocol — Architecture

• Model Context Protocol — Reference Filesystem Server

• Anthropic — Claude Code Settings

• Anthropic — Claude Code Permissions