Skip to content

Add an MCP server to Claude Code

Run claude mcp add --transport http <name> <url>, start Claude Code, type /mcp and sign in through the browser window it opens. Haechy is the example below, and the same steps work for any remote server. Put --scope user in the command if you want it in every project.

Checked on 18 November 2026 against Anthropic's Claude Code documentation.

Example 1: add Haechy

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

Then, inside Claude Code, run /mcp, pick haechy and follow the browser steps to sign in. Claude Code uses a temporary local address for the sign-in return and Anthropic's published client details, which Haechy accepts, so you enter no key. New users create their Haechy account in that same browser window (email and a password, then a text-message code), and the last page asks you to allow "Claude Code" to manage your Haechy apps. The quickstart covers what to ask next.

The command for any remote server

The pattern is the same for every remote server, and http is the transport Anthropic recommends:

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

For a server that wants a fixed key instead of a browser sign-in, add a header:

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

A server that runs on your own machine uses stdio. The -- separates Claude's options from the command that starts the server:

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

Server names can contain only letters, numbers, hyphens and underscores. The older SSE transport is deprecated: --transport http falls back to it automatically on Claude Code v2.1.265 or later, and --transport sse is there if you must ask for it.

Which scope should you use?

ScopeWho gets itShared with your team?Stored in
local (the default)Only you, in the current projectNo~/.claude.json
projectEveryone on the projectYes, through version control.mcp.json in the project root
userOnly you, in every projectNo~/.claude.json

Add it with --scope user or --scope project, for example claude mcp add --transport http --scope user haechy https://mcp.haechy.com/mcp. Each person still signs in to Haechy with their own account, even when the entry is shared. If the same name exists in more than one place, Claude Code uses the first of: local, project, user, plugin-provided servers, then claude.ai connectors. It uses that whole entry and doesn't merge fields.

A shared setup for a team: .mcp.json

With --scope project Claude Code writes a .mcp.json file that you commit. You can also write it by hand:

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

Claude Code asks each person for approval before using a server from .mcp.json. To reset those answers, run claude mcp reset-project-choices. Values such as ${VAR} are expanded in the file, so keys stay out of version control.

Add a server from JSON

If you have a server's configuration as JSON, add-json takes it directly. Pass the object for one server, without the mcpServers wrapper:

claude mcp add-json haechy '{"type":"http","url":"https://mcp.haechy.com/mcp"}'

Check it with claude mcp get haechy. Already set up servers in Claude Desktop? On macOS and Windows Subsystem for Linux, claude mcp add-from-claude-desktop opens a picker that imports them.

List, sign in, sign out and remove

  • claude mcp listShows each server as Connected, Needs authentication or Failed to connect. claude mcp get haechy shows one.
  • /mcp inside Claude CodePick a server and sign in through the browser. From a shell, claude mcp login haechy does the same, and --no-browser helps over SSH.
  • claude mcp logout haechyRevokes the sign-in at the server. Run it before removing, because claude mcp remove haechy deletes the stored tokens on your machine but doesn't revoke them at the server.

Already connected in claude.ai?

If you're logged in to Claude Code with a claude.ai account, connectors you added there are available automatically. They appear in /mcp marked as coming from claude.ai. This doesn't happen when Claude Code signs in another way, such as an API key. On Team and Enterprise, only admins can add servers there. See the claude.ai page for adding Haechy on that side, or the guide to custom connectors for any server.

How a folder gets deployed

When you deploy from a project folder, Claude prefers the upload route. Haechy gives Claude a one-time upload URL, valid for 30 minutes and for a single use, together with a shell command that packs the folder with tar and sends it with curl. That way a big app isn't pasted into the chat (inline deploys, with the files in the tool call, are limited to 2 MB).

The archive can be up to 25 MB and leaves out node_modules, .git, .env, __pycache__ and .venv. Haechy installs dependencies itself. What the app needs to run there is in Building an app for Haechy.

If it won't connect

What you seeWhat to do
MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)Run /mcp, select the server and sign in again.
MCP server sentry already exists in local config (your server's name)Run claude mcp remove <name> first, or use another name or scope.
has a "url" but no "type", in a hand-written entryAdd "type": "http" to the entry.
OAuth callback port <port> is already in useAnother program is holding the port. Close it, or find it with lsof -ti:<port> -sTCP:LISTEN.
The browser says the connection failed after you sign inPaste the full address from the browser's address bar into the URL prompt Claude Code shows.
Connectors from claude.ai are missingThey load only with a claude.ai login. Run /status, unset any API key setting, then /login.

Error texts from Anthropic's error list and MCP page, read 18 November 2026. A server that is slow to start can be given longer with MCP_TIMEOUT=10000 claude.

For Haechy, use --transport http. If Claude Code says Haechy needs authentication, run /mcp again and finish the browser sign-in.