How to Use MCP Servers with Claude

Claude is a host. An MCP server is the tool you attach to it. This guide stays on the public setup surface: the Claude Desktop config file, and the claude mcp add command documented for Claude Code. It does not invent a private API, and it does not ask you to install a pile of servers on the first afternoon.

If "MCP server" is still a fuzzy phrase, read what an MCP server is first. The short version: the protocol is shared, the server is one capability, and Claude is only the app that will call it.

Read the directory before you install

The failure mode for beginners is not a missing semicolon. It is connecting a powerful server because a list said it was popular. A browser server can click. A GitHub server can open issues and read private repositories your account can see. A voice or SEO server spends the account attached to it.

Start at the hand-picked MCP server list. It is a few official servers grouped by job — browser, GitHub, voice, SEO — plus the filesystem server the official local tutorial uses as the first example. Each row has a one-line description, the vendor's link, and a safety note. Pick one job you already have. Ignore the rest until that one connection is boring.

Two vendor pages are easy to misread. ElevenLabs tells you the old local repository is deprecated and points people at a hosted server that signs in with OAuth. Ahrefs says the same kind of thing about its old local package: it is archived, it expects an older API key, and the maintained path is the remote server. If a README says the install you are about to copy is outdated, believe the README.

Which Claude app you are configuring

Claude Desktop and Claude Code are different apps. They can both speak MCP. They do not share one settings screen.

• Claude Desktop is the chat app. You edit a JSON file, or use its Developer settings to open that file. Fully quit the app after a change so it reloads the servers.
• Claude Code is the terminal (and desktop) coding agent. You register servers with claude mcp add. The command writes a config file for you. Scope decides whether that registration is private to one project, shared with the repo, or yours across projects.

The public Claude Code docs also describe claude mcp add-from-claude-desktop on macOS and WSL, which copies servers you already configured in the Desktop app. Server names coming through that import can only use letters, numbers, hyphens, and underscores. A Desktop name with a space is skipped.

Claude Desktop: the config file

The official local-server tutorial uses Claude Desktop as the example host. The steps are: open Settings, open the Developer tab, and choose Edit Config. That button opens the JSON file rather than making you hunt for it. The paths, if you need them directly, are:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

The tutorial's first server is the filesystem server. You tell Claude Desktop to launch it with npx, and you pass only the directories it may see. Replace the username and the folders. Anything you leave out of args is not granted by this block.

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

Save the file, then quit Claude Desktop completely and open it again. A reload of the window is not the same thing. The app starts the server when it launches. If the server is missing, the usual causes are a JSON comma, a path that does not exist, or Node not being on the PATH the app sees.

That JSON shape is the one other local servers copy. A different package name and different arguments, still under mcpServers. For Playwright, Microsoft's README uses npx with @playwright/mcp@latest and no folder path, because the capability is a browser rather than a directory. Read that README before you paste it. A browser the model can drive is a larger grant than two folders on the Desktop.

Claude Code: claude mcp add

Claude Code's own docs, Connect Claude Code to tools via MCP, show two install shapes.

A remote server is a URL. The HTTP form is:

claude mcp add --transport http <name> <url>

The name is a label you choose. Claude Code uses it when it shows the server's tools and when you later run claude mcp remove. The URL is the vendor's. GitHub's README, for example, documents https://api.githubcopilot.com/mcp/ as the remote server, with OAuth or a personal access token. Do not invent a URL that is not in that vendor's docs.

A local server is a command. The docs spell it as:

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

The -- separates Claude's flags from the program that actually starts the server. If you already have an mcpServers JSON block written for Desktop, Claude Code can take the inner object through claude mcp add-json. The docs are specific here: pass the object inside mcpServers, not the wrapper. A URL entry with no type is read as a local process and fails. Add "type": "http" (or the server's real transport) when you copy a remote block across.

Where the command writes depends on scope:

• local (the default) — private to you, this project only, stored in ~/.claude.json under that project.
• project — .mcp.json at the repo root, so teammates get the same server. Do not put a secret in a file you are about to commit.
• user — yours, across projects, under the top-level mcpServers key in ~/.claude.json.

claude mcp get is how you check that the name you chose is the server you think it is. If a project file needs approval before Claude Code will use it, approve that file on purpose. An unexpected .mcp.json in a cloned repo is a set of tools you did not choose.

What people connect first

Match the server to a job, then stop. The directory has the source links. The pattern is:

• Files on this machine. The filesystem server, with two directories, not your home folder.
• A page in a browser. Playwright MCP, knowing it can act in a real browser session.
• A repository. GitHub's official server. Prefer the remote server's OAuth path when the host supports it, so a personal access token is not sitting in a JSON file.
• Speech. ElevenLabs' hosted server, not the deprecated local checkout.
• SEO data you already pay for. Ahrefs or DataForSEO remote servers, with that vendor's key, scoped as they document. These do not unlock a free crawl of the web.

After the server is connected, ask for something small and checkable. "List the files on the Desktop" tells you the filesystem server is alive. "Open a pull request" is a bad first test.

Permissions, local, and remote

An MCP connection is a permission decision that happens to be stored as JSON. Treat it that way.

• Local means it runs as you. The filesystem arguments are the allowlist. A browser server is not limited to a folder. A local GitHub server with a token can do whatever that token can do.
• Remote means someone else runs it. Your prompt, and any file or page you let the agent send, goes to that URL. Read who operates it. A vendor's hosted server and a random tunnel are not the same trust.
• Credentials do not belong in the chat, or in git. GitHub's README shows a personal access token as one option and OAuth as the other. If you use a token, prefer the host's secret prompt over pasting it into a committed .mcp.json. ElevenLabs' deprecation note exists partly so people stop copying an API key into the client.
• Tool results are context. Whatever the server returns is text the model will read. A web page, a README, or an issue can contain instructions. That does not make the server malicious. It means you do not give a brand-new server write access to a production repo while you are still learning the shape of the calls.
• Outdated install paths are a security note, not a style note. An archived local server can still run, with an old auth model, after the vendor has moved on. The directory marks the ones we saw vendors retire.

The broader permission problem — a grant that is wider than the task — is the same one on Are AI agents safe?. MCP does not retire that problem. It gives you a smaller object to grant: one server, one scope, one job.

FAQ

Related: What is an MCP server · MCP servers by use case · Build an AI agent with Claude · Are AI agents safe?

Next Steps

Pick one row from the directory, open the vendor's page, and connect only that server. The protocol page explains the roles if the config keys still feel arbitrary.

how do AI agents work — return to the complete AI agent architecture guide.