Claude Code MCP: add a server and check it works

You ask Claude Code why a signup keeps failing. It reads the code, explains the stack trace and refactors the module, and then you need to know whether the user exists in your database. Claude can’t check. It can’t query your project management API or look up a customer record either, because everything outside your local files is out of reach, so you copy the row across from another tab yourself. How do you give Claude Code access to those tools, and limit what it can do with them?

The Model Context Protocol (MCP) lets Claude Code reach them. It’s an open standard that connects Claude Code to outside tools and services through a simple server pattern, and a server here is a small program that sits between Claude and a service. Other assistants support MCP too, but the commands in this guide are Claude Code’s, so it’s for people who use Claude Code and are comfortable typing commands in a terminal.

Part 1 of 4 Learn

What an MCP server is

An MCP server is middleware. It sits between your AI and another piece of software, like a semi-permeable membrane: it offers your AI a set list of tools, the AI asks for one with the details of the job, and the server passes that request to the other software and brings the result back. Nothing gets through that the server doesn’t offer.

A server can offer three kinds of thing. Tools are actions Claude can take, such as “create issue” on a GitHub server. Resources are data Claude can read, such as a file in a repository. Prompts are pre-built instructions, such as a saved code-review request. This guide only uses tools.

When Claude Code starts, it loads your configured MCP servers and treats their tools the same way it treats its built-in tools like Bash, Read, and Edit. If you’ve connected a GitHub server, Claude can create issues. If you’ve connected a database server, Claude can run queries. Claude doesn’t need special instructions: it sees the available tools and uses them when relevant.

Claude Code can connect to a server in two ways:

• stdio (standard input and output, the way two programs on one computer talk to each other): the server runs as a local process on your machine. This suits tools that work on your own files, like the filesystem server below.
• HTTP: the server runs remotely and Claude Code connects to its URL. This is how hosted services like GitHub’s server work. An older remote type, SSE, is deprecated, so use HTTP where a service offers it (Anthropic’s MCP docs, checked 5 November 2026).

This guide starts with a stdio server, then adds GitHub’s hosted HTTP server.

Add your first MCP server

Claude Code’s built-in command for a local server has this shape:

claude mcp add <name> -- <command> [args...]

The -- separates Claude Code’s own options (such as --scope or --env) from the command that starts the server. Claude Code passes everything after it to the server as it is.

The filesystem server is a good first test. It gives Claude access to directories outside your current project, which helps if you work across several folders or keep reference documents elsewhere. You would add it like this:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/Documents /Users/you/Downloads

Each path you list is a directory the server will expose, and Claude can’t read anywhere else through it. Swap in directories you actually want Claude to reach.

Servers load at startup, so after you add one, start a new Claude Code session and type:

/mcp

filesystem should be listed as connected. If /mcp shows it as failed or missing, check the paths you gave and check that node --version shows 24 or later. Asking Claude to list your Documents folder doesn’t prove the server works, because Claude Code can often list a folder with its own built-in tools; /mcp does.

claude mcp get filesystem shows how the server is saved. Saved by hand, the same server looks like this in a JSON file:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
               "/Users/you/Documents",
               "/Users/you/Downloads"]
    }
  }
}

To share a server with a project, put a block like that in .mcp.json at the project root, using paths that exist for everyone (for example relative to the project).

Connect GitHub, a hosted server

The filesystem server only reaches local files. The GitHub MCP server lets Claude create issues, manage pull requests, search repositories and read code, all within your normal conversation.

GitHub runs this server for you, so there’s nothing to install. Anthropic’s docs recommend creating a fine-grained personal access token with access only to the repositories you want Claude to work on, then adding the server:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

Replace YOUR_GITHUB_PAT with your token (the command is from Anthropic’s MCP docs, checked 5 November 2026; GitHub’s Claude install guide shows an equivalent claude mcp add-json form). The command doesn’t check your credentials, so open /mcp afterwards and look at the github row.

With the server connected, Claude can do things like “create a GitHub issue for the bug we just found” or “show me the open PRs on this repo” without you switching to the browser. If you already have the gh command-line tool installed, Claude can also run it directly. Anthropic’s cost guidance says CLI tools like gh are more context-efficient than MCP servers because they don’t add a per-tool listing. If gh already does what you need, you may not need the GitHub MCP server.

Choose where Claude Code saves a server: local, project or user

claude mcp add saves the server at one of three scopes, and --scope picks one:

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

If the same server name exists at more than one scope, local wins over project, and project over user; Claude Code uses the whole entry from the winning scope and doesn’t merge fields. Claude Code also asks for your approval before it uses a server from a project’s .mcp.json, and claude mcp reset-project-choices clears those answers.

A reasonable setup puts tools you want everywhere, like GitHub or web search, at user scope. A project’s database server goes at local scope, and anything the whole team needs goes at project scope, committed in .mcp.json. Keep credentials out of .mcp.json, because it’s meant to be shared. Run claude mcp get <name> to see which scope a server is saved in.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/your/folder

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

Claude Code loads MCP tools on demand

Connecting more servers costs far less context than it used to. Claude Code uses tool search by default: MCP tool definitions are deferred, so only tool names and server instructions load at the start of a session, and Claude loads the tools it needs when a task calls for them. Anthropic’s MCP docs say this means adding more servers “has minimal impact on your context window” (Scale with MCP tool search, checked 5 November 2026).

Three exceptions load every tool upfront. One is a model earlier than Opus 4 or Sonnet 4. Another is setting ENABLE_TOOL_SEARCH=false, and the third is a Microsoft Foundry deployment hosted on Azure. If you route Claude Code through an LLM gateway, the gateway has to pass the tool-search fields through. Run /context to see what is using space in your own session.

Tool results still count. Claude Code shows a warning when an MCP tool’s output exceeds 10,000 tokens and limits output to 25,000 tokens by default, so a server that returns whole tables can still fill your conversation.

The number of tools a server offers also affects how much context it uses. Cloudflare says its API has over 2,500 endpoints, and that exposing each one as an MCP tool would consume over 2 million tokens. Its own server offers two tools, search() and execute(), which take around 1,000 tokens (Cloudflare’s Code Mode post, checked 5 November 2026). You probably don’t have 2,500 endpoints, but a server with a few well-designed tools is easier for Claude to use than one that exposes every possible action.

Every server you leave connected is also access you have granted, so remove the ones you’ve stopped using:

• Check what you’ve connected. Run claude mcp list to see your servers and their health, and /usage on a Pro, Max, Ultra, Team or Enterprise plan to see how much of your recent usage each MCP server accounted for.
• Remove what you don’t use. claude mcp remove <name> deletes a server. Run claude mcp logout <name> first if it used a sign-in, because removing a remote server deletes the tokens Claude Code stored but doesn’t revoke them at the service.
• Pick the narrow scope. Your email server doesn’t need to be available when you’re debugging a CSS layout, so save it at local scope for the project that needs it.

Build your own server or use an existing one

For common services such as GitHub, Slack, databases and web search, look for an existing server first, and use an actively maintained one if it covers most of what you need. Prefer servers that your vendor lists in its own directory, or that the organisation behind the service supports. Anthropic’s docs say to verify you trust each server before connecting it, because servers that fetch external content can expose you to prompt injection. The MCP Registry lists published servers.

Build your own when:

• Your service has no existing server. Internal APIs, custom databases, proprietary tools.
• You need tight permission scoping. An existing server might expose more actions than you want Claude to have. A custom server can expose exactly the three operations you trust.
• You’re wrapping a CLI tool. If you already have a working command-line tool for a service, wrapping it as an MCP server is often simpler than finding a standalone server.

If your API has good documentation and an existing SDK, a basic MCP server is usually a small project, and the MCP documentation covers the protocol and SDKs. If your service is complex and an actively maintained server exists, use that one.

Give each server the least access it needs

When you connect an external service, think about what Claude can do through that connection. A GitHub token with access to every repository and your organisation’s settings is more than Claude needs to create issues. A database connection with write access is more than Claude needs to answer questions about your data. The principle of least privilege applies here as it does anywhere in security:

• Use read-only database connections unless you want Claude to write data.
• Scope API tokens narrowly. Create dedicated tokens for MCP use with only the permissions the server needs.
• Separate read and write servers if your service supports it. You might want Claude to always be able to query your database, but only write to it in specific projects.

Claude Code asks for permission before it uses an MCP tool, unless you have allowed that tool. A rule such as mcp__github__* allows every tool from the github server, and mcp__github__<tool> allows one (Anthropic’s permissions docs, checked 5 November 2026). Loosen permissions bit by bit. , If Claude is allowed a tool it shouldn’t use, a token with narrow access still limits what that tool can do.

When a server doesn’t connect

If a server doesn’t connect, start with these checks:

• A server shows as failed. Check the paths and node --version for a local server, then try /mcp reconnect <server>.
• A server stopped working mid-conversation. claude mcp list shows each server’s health.
• A service Claude used to reach is now refused. Tokens expire, so check your credentials first.

Part 2 of 4 Practise

Try it on your own work

1. Pick a folder you want Claude to read that is outside your current project, and add the filesystem server for it: claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/your/folder.Result the command finishes without an error and names the new filesystem server.

2. Start a new Claude Code session and type /mcp.Result filesystem is listed as connected. If it shows as failed, check the path and node --version.

3. Run claude mcp get filesystem in your terminal.Result the output shows the command, the folder you gave it and the scope it was saved at, which is local unless you chose another.

4. Ask Claude to list the files in that folder, then to read one.Result Claude names files from the folder and shows the contents of the one you picked, and it can’t read a folder you didn’t list.

5. Decide the scope for your own server. Write one line saying who needs it (only you here, only you everywhere, or the whole team) and the matching scope.Result one line such as “only me, every project: user”, and a command with --scope to match.

6. Run claude mcp list and name any server you haven’t used this month. Remove one with claude mcp remove <name>.Result the list no longer shows the server you removed, or you’ve checked that you use every server on the list.

Part 3 of 4 Check

Check yourself

Part 4 of 4 Keep

Read next

• Setting Up Your First CLAUDE.md File: tell Claude when to use the tools you just connected.
• Claude Code /insights: audit how you work with it: the report can suggest an MCP server when Claude can’t reach a tool you use.
• What claude doctor and /doctor check: another built-in Claude Code check, this time on your setup.