Add an MCP server to Claude Code

Install the Claude Code CLI.

Install from Anthropic’s setup page, then check the binary:

claude --version

2.1.310 (Claude Code)

That is the version used for every command below, on October 24, 2026. The shell was a throwaway git repo at /tmp/shipmunks-mcp-lab/project, so project scope had a root to write into. Run the commands in your own project the same way: in the terminal, not inside a claude chat. Inside a session you use /mcp for servers that are already configured.

Add a stdio server.

stdio means Claude Code starts a program and exchanges JSON-RPC messages on that program’s standard input and output. No port, no URL.

The server here is the public filesystem reference server, @modelcontextprotocol/server-filesystem. Its README says it may touch only the directories you pass on the command line, and that Node.js 24 or later is the requirement when you run it through npx. I passed one notes folder that held a single text file.

claude mcp add --scope local --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp/shipmunks-mcp-lab/project/notes

Added stdio MCP server filesystem with command: npx -y @modelcontextprotocol/server-filesystem /tmp/shipmunks-mcp-lab/project/notes to local config
File modified: /home/ubuntu/.claude.json [project: /tmp/shipmunks-mcp-lab/project]

The -- is the separator. Claude Code’s flags stay on the left. The program and its arguments stay on the right. --scope local is the default, written out here so the line shows which of the three scopes it is. Pass a directory you are willing to let an agent read and write. Swap the path for yours.

Add a remote HTTP server.

Streamable HTTP is the spec’s name for a remote server at a URL. Claude Code’s flag for it is --transport http. Nothing is installed for that server.

This one is ContextBolt SEO, which we make. The MCP endpoint is https://seo.contextbolt.app/mcp.

claude mcp add --scope local --transport http contextbolt-seo https://seo.contextbolt.app/mcp

Added HTTP MCP server contextbolt-seo with URL: https://seo.contextbolt.app/mcp to local config
File modified: /home/ubuntu/.claude.json [project: /tmp/shipmunks-mcp-lab/project]

The name contextbolt-seo is one I chose. The URL is the part that matters. I passed no token and no header.

Read the status with claude mcp list.

add writes the config. The status comes from a second command, which actually connects:

claude mcp list

Checking MCP server health…

filesystem: npx -y @modelcontextprotocol/server-filesystem /tmp/shipmunks-mcp-lab/project/notes - ✔ Connected
contextbolt-seo: https://seo.contextbolt.app/mcp (HTTP) - ! Needs authentication

claude mcp get prints the scope and the command or URL.

filesystem:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: stdio
  Command: npx
  Args: -y @modelcontextprotocol/server-filesystem /tmp/shipmunks-mcp-lab/project/notes
  Environment:

To remove this server, run: claude mcp remove filesystem -s local

contextbolt-seo:
  Scope: Local config (private to you in this project)
  Status: ! Needs authentication
  Type: http
  URL: https://seo.contextbolt.app/mcp

To remove this server, run: claude mcp remove contextbolt-seo -s local

Connected means the filesystem process started. Needs authentication means the URL was reached and wants a login. I stopped there for the HTTP server. I did not run claude mcp login, I did not open a browser, and I did not start a claude session, so I never called a tool on either server.

A request to that URL with no token came back HTTP 401. The www-authenticate header asked for a Bearer token with scope mcp. That matches the list status. It is not a bad URL.

Save a shared server in .mcp.json.

A server’s scope is fixed when you add it. Moving it means removing that entry and adding it again. I took the filesystem server off local scope and put it on project scope, which is the one that lands in the repo:

claude mcp remove filesystem --scope local
claude mcp add --scope project --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp/shipmunks-mcp-lab/project/notes

Added stdio MCP server filesystem with command: npx -y @modelcontextprotocol/server-filesystem /tmp/shipmunks-mcp-lab/project/notes to project config
File modified: /tmp/shipmunks-mcp-lab/project/.mcp.json

The file it wrote:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/tmp/shipmunks-mcp-lab/project/notes"
      ],
      "env": {}
    }
  }
}

On Windows the filesystem README launches npx through cmd /c. I did not run that. I am on Linux.

The next claude mcp list did not connect yet:

filesystem: npx -y @modelcontextprotocol/server-filesystem /tmp/shipmunks-mcp-lab/project/notes - ⏸ Pending approval (run `claude` to approve)

That pause is deliberate. A cloned repo should not be able to start a process on your machine until you say so. The docs say to run claude in the folder and approve the server. This shell was not interactive, so I used the other switch those docs name, enableAllProjectMcpServers, in the user settings file ~/.claude/settings.json. That approves every project server, which is broader than approving one. After it was set, claude mcp get filesystem reported scope Project config (shared via .mcp.json) and status ✔ Connected.