How to Install an MCP Server for Claude Code

What Problem This Solves

Claude Code is an AI agent in your terminal. Out of the box it reads and edits files and runs shell commands, but it can't query your issue tracker, a live database or a SaaS API. An MCP server fills that gap by exposing a standard set of tools Claude can call.

Examples of what MCP servers unlock:

• GitHub MCP: PR status, issues, branches, Actions runs
• Database servers: inspect schemas and run read-only queries
• Playwright MCP: automated browser testing and page snapshots
• Context7: current, version-specific library documentation

MCP is one of several ways to extend Claude Code, alongside skills, hooks, subagents and plugins (which can bundle MCP servers). With tool search on by default, Claude Code loads only tool names at startup and fetches full tool definitions when it needs them.

Prerequisites

• Claude Code installed and running. Check with claude --version.
• Node.js 18 or newer for servers started with npx (check each server's README for its own requirement). Docker if the server ships as a container.
• Credentials if the server needs them: a GitHub personal access token, a database URL, an API key. Remote servers may use OAuth instead.
• The server's install details from its README or the official MCP Registry: a remote URL, or the command that starts it locally.

Installation Steps

Step 1: Pick the server and its transport

Every server is either remote (you connect to a URL over HTTP) or local (Claude Code starts it on your machine over stdio). The README tells you which, and gives the URL or start command.

Step 2: Add a remote server

GitHub's official server is remote. With a personal access token:

Breakdown:

• claude mcp add: registers a server
• --transport http: connect to a remote URL (SSE is deprecated; use HTTP where available)
• github: the name you give the server
• --header: sends your token with every request

If a remote server uses OAuth instead of a token, add it without the header, then run /mcp inside Claude Code and follow the browser sign-in. Claude Code stores and refreshes the token for you.

Step 3: Add a local server

Local servers start as a child process. Everything after -- is the command that starts the server:

If a local server needs a secret, pass it as an environment variable with --env (or -e) before the server name:

Step 4: Confirm installation

Each server is listed with its health status. Inside a session, /mcp shows the same information and lets you sign in, reconnect or inspect a server.

Transport Types: stdio vs HTTP

stdio (local servers)

Claude Code starts the server as a child process and talks to it over standard input/output. Use it for tools that run on your machine (Playwright, local database tools, CLI wrappers). Claude Code doesn't automatically reconnect a stdio server that crashes; reconnect it from /mcp.

HTTP (remote servers)

Use HTTP when the server is hosted by a vendor or shared by your team. It's the recommended transport for remote servers; SSE is deprecated. Claude Code retries a dropped remote connection automatically, up to five times with exponential backoff.

Config scope: local, user, or project

By default a server is added at local scope: available only to you, in the current project. Use --scope to change that (MCP docs):

• --scope local (default): only you, only this project. Stored in ~/.claude.json under the project's path.
• --scope user: only you, in all projects. Stored in ~/.claude.json.
• --scope project: everyone who clones the repo. Stored in .mcp.json at the project root; commit it, and keep secrets out of it.

Verify the Server Connected

After claude mcp add, check the server is actually usable:

1. Check status

2. Inspect one server

This shows the server's configuration and health; for a failed connection it includes an Issue: line with the HTTP status or error code. Project-scoped servers you haven't approved yet show as pending approval.

3. Test in a session

Start Claude Code, run /mcp to confirm the server is connected, then ask for something that needs it. For GitHub:

If Claude doesn't use the server's tools, open /mcp, select the server and check its status and error.

Common Pitfalls & Troubleshooting

1. Server fails to connect

Run claude mcp get <name> and read the Issue: line. For a local server, run its start command by hand in another terminal to see the real error (missing package, wrong Node version, missing environment variable):

2. Tools don't show up, or are out of date

In a session, run /mcp, select the server and choose Reconnect. That also discards the server's cached tool list.

3. Config errors in .mcp.json

One missing comma breaks the whole file. Validate it:

Python prints the line and column of any syntax error. User- and local-scope servers live in ~/.claude.json; prefer editing them with claude mcp add/remove over editing that file by hand.

4. Authentication fails

• Token-based servers: check the header or environment variable was passed when you added the server
• OAuth servers: run /mcp, select the server and complete the browser sign-in; claude mcp get <name> shows whether OAuth credentials are configured
• Databases: check the connection string format, postgresql://user:password@host:port/database

5. A teammate doesn't see the server

Local and user scope are private to you. To share a server, add it with --scope project and commit .mcp.json. Teammates approve project servers the first time they load them.

FAQ

Q: Do I need to code to install an MCP server?

No. A remote server is a URL plus a token or sign-in; a local server is one claude mcp add command. If you can follow a README, you can install either.

Q: Can I install several servers?

Yes, one claude mcp add per server. With tool search on by default, idle servers cost little context, but each one is more code with access to your credentials, so start with the 3–5 you will actually use.

Q: What if the server wants write access to my database or files?

Use scoped tokens with the minimum permissions the server needs, and prefer read-only roles unless you explicitly want writes. That limits what a mistaken tool call can change.

Q: How do I remove a server?

Related reading

• MCP Servers
• Skills directory
• How to install Claude Code skills