How to Install an MCP Server in Claude Code

To install a local MCP server in Claude Code, run claude mcp add with a name and the command that starts your stdio server, choose the narrowest appropriate scope, and confirm the connection with claude mcp get, claude mcp list, and /mcp. The steps below explain each decision without requiring another product.

Before you run the add command

You need a local MCP server that communicates over standard input and output. In every example below:

• local-tools is a harmless example name. You may replace it with a short name for your server.
• node is the executable used to start the example server.
• /absolute/path/to/your-mcp-server.mjs is a placeholder, not a file supplied by this article. Replace it with the absolute path to your own stdio MCP server before running any add command.

First, confirm that the executable and server file you intend to use are available:

node --version
test -f /absolute/path/to/your-mcp-server.mjs

The second command succeeds silently only after you replace the placeholder with a real file path. If your server starts with Python, uvx, npx, or another executable, use that command and its arguments after -- instead.

Choose a Claude Code scope

Claude Code supports three scopes for manually added MCP servers:

• Local scope is the default. It stores the server under the current project’s entry in ~/.claude.json and keeps the configuration private to you and that project.
• Project scope stores the server in .mcp.json at the project root so the configuration can be reviewed and shared with the team.
• User scope stores the server in ~/.claude.json and makes it available across your projects.

Use the narrowest scope that matches how you intend to use the server.

Keep secrets out of shared configuration

Do not put tokens or passwords directly in a project-scoped .mcp.json. Reference environment variables such as ${API_TOKEN} instead, and set those values separately on each computer. Local and user entries are private to your account, but they still deserve normal credential hygiene: prefer OAuth when the remote server supports it, rotate exposed values, and never commit ~/.claude.json.

Add a local-scoped server

Run the command from the project where you want to use the server:

claude mcp add --transport stdio local-tools -- node /absolute/path/to/your-mcp-server.mjs

The order matters. Claude Code options such as --transport, --env, and --scope belong before the server name. Everything after -- is passed to the server process unchanged.

Add a project-scoped server

To create a team-shareable project entry, run this command from the project root:

claude mcp add --transport stdio --scope project local-tools -- node /absolute/path/to/your-mcp-server.mjs

Claude Code writes project-scoped servers to .mcp.json. Review that file before committing it, never place secrets directly in it, and expect Claude Code to request approval before using a project-scoped server.

Add a user-scoped server

To make the server available across your projects, use user scope:

claude mcp add --transport stdio --scope user local-tools -- node /absolute/path/to/your-mcp-server.mjs

User-scoped configuration remains private in ~/.claude.json, but every project you open can use the server.

Verify the Claude Code connection

Inspect the named server and then list all configured servers:

claude mcp get local-tools
claude mcp list

Inside Claude Code, /mcp displays server status. A project-scoped server may remain pending until you open Claude Code in the workspace and approve it. Once connected, ask Claude Code to list the tools exposed by local-tools to confirm that the server initialized and advertised its tools.

Troubleshoot a server that does not connect

If the server is listed but fails to start:

1. Run node /absolute/path/to/your-mcp-server.mjs directly after replacing the placeholder.
2. Confirm the executable resolves on your PATH and the server file uses an absolute path.
3. Use claude mcp get local-tools to confirm the scope, command, and arguments Claude Code retained.
4. Check whether the server needs environment variables and pass them with --env KEY=value before the server name.
5. For project scope, open Claude Code in the workspace and approve the pending .mcp.json entry.
6. Check /mcp again after correcting or approving the configuration.

Official sources

These instructions were checked against the following vendor documentation.

• Anthropic: Connect Claude Code to tools via MCP