How to Add and Configure MCP Servers in Claude Code

Claude Code connects to external tools and data through MCP, the Model Context Protocol. MCP is an open standard that lets an AI client communicate with servers that provide tools or data. Claude Code is the client. The MCP server provides tools or data, and the transport is the method Claude Code uses to communicate with it. Adding a server makes its tools available to Claude Code, while the server’s credentials and permissions determine what those tools can access.

Choose a transport, which sets how Claude Code communicates with the server, and a configuration scope, which sets which projects load it. Configure the server with the claude mcp add command or a JSON configuration, then check its connection and authentication status before relying on it. The Claude Code MCP reference explains which transports and scopes are available, how to use the commands, and how approval works.

Choose a transport for the server

Use HTTP for a hosted server when it supports HTTP. Use stdio, which lets Claude Code communicate with a program through standard input and output, when it needs to start a local command-line program or script. The current Claude Code documentation marks Server-Sent Events (SSE), a way for a server to send updates over an HTTP connection, as deprecated and recommends HTTP when the server offers it.

For a remote HTTP server, run:

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

Use the endpoint and authentication method documented by the service you are connecting to. If the server expects an authorization header, add one with --header:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

The example token is a placeholder. Do not use it as a credential.

Claude Code starts the local server process and passes it the configured environment variables. Put -- between Claude Code’s options and the server command:

claude mcp add --env API_KEY=YOUR_KEY --transport stdio example \
  -- npx -y @example/mcp-server

Options before -- configure Claude Code; the command and arguments after it start the server. Replace the example key and package with the values specified by the server’s provider.

Claude Code also documents WebSocket connections for remote servers that need a persistent, two-way connection. The claude mcp add --transport flag does not accept ws, so configure a WebSocket server through JSON instead. For servers that only offer SSE, use the documented compatibility path; Claude Code v2.1.265 and later can fall back from an HTTP connection attempt to SSE.

Choose where Claude Code stores the configuration

Claude Code offers three scopes. The scope determines which projects load a server and where Claude Code stores its configuration:

• Local is the default. It applies to the current project and stays private to the user. Claude Code stores its configuration under that project’s entry in ~/.claude.json.
• Project stores the configuration in .mcp.json at the project root. Commit this file only when the project’s users should share the server configuration.
• User stores the configuration in ~/.claude.json and makes it available across the user’s projects.

For example, add a project-shared HTTP server by specifying --scope project:

claude mcp add --scope project --transport http notion https://mcp.notion.com/mcp

Use local scope for a personal project connection. Use project scope when the configuration should be shared. Before committing .mcp.json, check that it contains no passwords, API keys, or other secrets. Sharing a server definition does not make embedded credentials safe.

Configure a server in JSON

A project can store server definitions in .mcp.json under an mcpServers key. For example:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

A remote JSON entry needs a transport type as well as its URL. If the entry has a url but no type, Claude Code interprets it as stdio, and the connection fails.

When importing a configuration from another MCP client with claude mcp add-json, pass the server object inside mcpServers, rather than the outer object containing the mcpServers key. Check imported server names too: Claude Code expects letters, numbers, hyphens, and underscores.

Authenticate and review access

The server’s instructions specify its authentication method. If a remote server supports OAuth 2.0, a standard that lets you authorize access through a sign-in flow, Claude Code can start browser sign-in from its /mcp command. Another server might require a configured header, such as a bearer token or API key.

Keep credentials out of shared configuration files, and give each credential only the access the server needs. For database connections, use a read-only database account when the task only requires reading data. Before connecting, check who operates the server and what permissions it has. The server’s tools can use the access granted by its credentials. External content that a server retrieves can also contain instructions designed to manipulate Claude Code, known as prompt-injection attempts.

In an interactive session, Claude Code asks for approval before using a project-scoped server from .mcp.json. You can reset those approval choices with:

claude mcp reset-project-choices

That prompt is not available in every session type. In claude -p runs, Agent SDK sessions, and some cloud sessions outside a project’s threads, Claude Code loads project-scoped servers without asking. Review shared server configuration with those uses in mind.

Check the connection and diagnose failures

Adding a server saves its configuration, but does not confirm that Claude Code can reach it or authenticate with it. Check the CLI status and configuration with:

claude mcp list
claude mcp get 

Inside Claude Code, run /mcp to inspect server status and see how many tools a connected server provides. A server marked pending approval or disabled has not necessarily failed a connection attempt; those statuses describe its configuration or approval state.

The MCP reference describes status details and connection behavior. When a server fails to connect, inspect its remote JSON entry for the correct type and check whether its project configuration is awaiting approval or disabled. Then compare its authentication method with the server’s instructions. For a stdio server, verify that the executable and its arguments appear after --. A 401 or 403 response can indicate that the server requires OAuth. If you configured an authorization header, Claude Code reports a connection failure instead. Check the header and token rather than assuming an OAuth sign-in will fix the problem.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com