How to Add an MCP Server to Claude Code (CLI Guide)

Adding an MCP server to Claude Code means running one CLI command, claude mcp add, that registers either a local subprocess or a remote HTTP endpoint in Claude Code's config. Claude Code then starts (or connects to) that server, negotiates capabilities over MCP, and exposes its tools inside your session. The exact command differs slightly for a local server, a remote server, and one that needs an API key or OAuth.

Add a remote MCP server with claude mcp add --transport http

Run this from a normal terminal, not from inside a running claude session:

claude mcp add --transport http <name> <url>

--transport http (short form -t http) tells Claude Code the server speaks Streamable HTTP rather than running as a local process; if you configure the same server directly in JSON (.mcp.json, ~/.claude.json, or claude mcp add-json) the type field accepts streamable-http as an alias for http. sse is also accepted as a transport but is being phased out in favor of Streamable HTTP. If the server needs an API key, add it as a header with --header (short form -H) instead of putting it in the URL:

claude mcp add --transport http mcpifex https://mcpifex.com/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

That's the same pattern GitHub's own hosted MCP server installation guide uses for its bearer token, and it's exactly how MCPifex's gateway expects a key — see the MCPifex-specific section below.

Add a local MCP server that runs as a subprocess

stdio is the default transport, so you can omit --transport entirely for a server that runs on your machine as a child process. Everything after -- is the command Claude Code will spawn:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Claude Code manages the subprocess's lifecycle for you — starting it on first use and killing it when the session ends — but you're still responsible for whatever that command needs on your machine: a working Node.js/npx install, network access for the first npx download, any environment variables the package reads. That's the trade-off a local server always carries, and it's the one a hosted server (MCPifex included) removes entirely, since nothing runs on your machine at all.

Add a server as raw JSON, or edit .mcp.json directly

claude mcp add-json takes the same configuration as a single JSON object, which is the only way to add a WebSocket server ("type": "ws") since there's no dedicated flag for it:

claude mcp add-json mcpifex '{"type":"http","url":"https://mcpifex.com/mcp","headers":{"Authorization":"Bearer <YOUR_API_KEY>"}}'

You can also hand-edit the scope's config file directly (paths in the next section). A project-scoped .mcp.json entry looks like this for an HTTP server:

{"mcpServers": {"mcpifex": {"type": "http", "url": "https://mcpifex.com/mcp"}}}

and like this for a local one:

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

Values inside .mcp.json support environment-variable expansion — ${VAR} or ${VAR:-default} — so a team can commit the file without committing secrets. Claude Code reads .mcp.json at session start, so a hand-edit needs a restart before it takes effect.

Choose a scope: local, project, or user

Every claude mcp add takes a --scope (-s) flag, defaulting to local:

project scope is the right choice for a server the whole team should get automatically, like a shared MCPifex gateway credential used only for read-only tools; local or user is right for anything tied to your own account or API key.

Verify the connection with claude mcp list or /mcp

claude mcp list prints every configured server and its live status:

claude mcp list
claude mcp get <name>
claude mcp remove <name>

Status shows as ✔ Connected, ! Connected · tools fetch failed, ! Needs authentication, ✘ Failed to connect, ✘ Connection error, ⏸ Pending approval, or ⊘ Disabled for this project (legacy Windows consoles render the check and cross as √/×). Inside a running session, /mcp shows the same status and lets you authenticate, disable, or inspect one server without leaving the conversation.

Authenticate an OAuth-backed server

An OAuth-backed server (Anthropic's own docs use Sentry as the example) is added exactly the same way as any other HTTP server — claude mcp add --transport http <name> <url> — and shows ! Needs authentication in claude mcp list until you complete sign-in. Run /mcp, select the server, and choose "Authenticate" to open the browser flow; claude mcp login <name> and claude mcp logout <name> do the same from outside a session. If the provider requires a pre-registered OAuth app, pass --client-id and --client-secret (which prompts rather than taking the secret as plain text) and optionally --callback-port.

Fix "Failed to connect" and other common errors

Two things account for most first-run trouble. First, a local npx-based server can show ✘ Failed to connect the very first time simply because the package is still downloading — re-run claude mcp list once it finishes rather than assuming the config is wrong. Second, a slow server can hit Claude Code's 30-second startup timeout; raise it with the MCP_TIMEOUT environment variable, in milliseconds, before launching claude:

MCP_TIMEOUT=60000 claude

For a remote server, a ✘ Failed to connect or ✘ Connection error almost always means one of: a wrong URL, a missing or expired auth header, or a 401/403 from the server itself — claude mcp get <name> prints the full config and the last error detail. "Server already exists" just means the name you picked is already registered at that scope; either claude mcp remove it first or pick a different name.

Connect Claude Code to an MCPifex-hosted server

As of September 2026, every server MCPifex hosts is added with the exact same command shown above, because MCPifex is a single remote MCP server, not a different package per tool: create an instance of a catalog server in the portal (PostgreSQL is one example — see the PostgreSQL server page, or browse the full marketplace listing first), generate an API key from that same portal, then run:

#!/bin/sh
# MCPifex — Claude Code CLI snippet.
# Replace <YOUR_MCPX_KEY> with your MCPifex API key (starts "mcpx_"), from
# the portal's API key page, then run this once from any shell that has the
# `claude` CLI on PATH.
claude mcp add mcpifex --transport http https://mcpifex.com/mcp \
  --header "Authorization: Bearer <YOUR_MCPX_KEY>"

Confirm it with claude mcp list the same way you would any other server. The difference from a typical add is what happens before that command: instead of installing a package and hoping its dependencies resolve on your machine, you pick which of the server's tools are enabled inside the portal, with anything destructive off by default, and the gateway enforces that allow-list on every tools/call — a tool you didn't enable is refused whether or not the underlying package supports it. Add a second hosted server the same way, with its own instance and key, and it still points at the identical https://mcpifex.com/mcp URL; only the header changes. If you revoke a key from the portal, new calls stop within about a minute, and a session that's already open is cut off on its next tool call. The full walkthrough, including generating the key, is in the MCPifex quickstart; a free account (register here) covers 3 instances before you need a paid plan.