How to connect Claude to an MCP server

Claude connects to MCP servers three different ways, and picking the wrong one is the usual reason a setup doesn’t work. The short version: local servers run on your machine over stdio, remote servers connect over HTTP with real authentication, and Claude Desktop can install either from a bundle.

Unfamiliar with the underlying idea? What is an MCP server covers it first.

Which connection type do you need?

If the thing you’re connecting is…	Use	Why
On your own machine (files, a local site, a repo)	Local / stdio	Nothing crosses the network
A hosted service or a live site	Remote / HTTP	Needs real authentication
Something you want installed in one click	Desktop extension	Bundles the server and its config

Picking the wrong one is the usual reason a setup fails — the mismatch rarely announces itself in the error.

The common mistake is trying to run a local-style server against a remote site. If a config launches a subprocess with a command, that subprocess runs on your computer, so it can only reach things your computer can reach. Pointing it at a server you only have web access to won’t work, and the error rarely says so.

Claude Code

Claude Code reads a .mcp.json in your project root. Local servers are declared as a command it will run:

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@scope/some-mcp-server"]
    }
  }
}

Restart Claude Code afterwards. Config is read at startup, not watched.

Because .mcp.json frequently holds credentials, check whether it’s gitignored before you put anything real in it. It’s an easy way to publish a token to a public repository.

Claude Desktop

Claude Desktop reads claude_desktop_config.json:

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

Same shape as above. Two things catch people out:

Use absolute paths. The app doesn’t launch from the directory you think it does. Relative paths fail with errors that don’t mention paths.

Quit properly. Closing the window isn’t enough on either OS; the process keeps running with the old config. Quit fully and relaunch.

Desktop extensions (`.mcpb`)

Claude Desktop also installs bundles: a single file containing the server and its configuration, installed by double-clicking. No JSON editing, no path debugging.

If a server offers a bundle, take it. EMCP Tools generates one from its Connection tab with your site URL and credentials already filled in, which removes the two most common failure modes at once.

Remote servers

Remote servers connect over HTTP and need authentication. Two approaches, and the difference matters:

OAuth is the better one. You approve access once in a browser, the client holds a token, and you can revoke it later like any other connected app. No credential ever gets pasted into a config file. GitHub’s hosted MCP server works this way, and so does ours.

If a server supports OAuth, use OAuth — the whole class of leaked-credential problems simply never arises.

Application passwords or API tokens work everywhere but put a long-lived secret in a config file on disk. Fine for a local experiment, worth avoiding for anything you care about.

If a server supports OAuth, use OAuth. The whole class of “I committed my config and leaked a token” problems disappears.

When no tools appear

Claude connects, reports no error, and has no tools. In rough order of likelihood:

Test the server independently before blaming the client — it settles in seconds whether the fault is the server or the connection.

1. The client wasn’t fully restarted. Genuinely the most common cause. Quit the application, don’t just close the window.

2. The tool cap. Some clients refuse to load a server past a limit, and they do it silently. Antigravity caps at 100 tools across all servers. A server registering more than that just doesn’t appear, with nothing in the UI to say why. Servers that anticipate this offer a compact mode that collapses the surface to a handful of dispatcher tools.

3. The config is valid JSON but wrong. A trailing comma stops the whole file parsing, and most clients don’t report it. Paste it into a JSON validator.

4. Authentication failed. For remote servers, confirm the credentials work outside the client first, with curl or a browser.

5. The server isn’t actually running. For stdio servers, run the exact command from your terminal. If it fails there, it fails in Claude too.

A useful habit: test the server independently before blaming the client. The MCP Inspector will talk to any server and show you exactly which tools it exposes, which settles in seconds whether the problem is the server or the connection.

Once it’s connected

You don’t call tools directly. You describe what you want, and Claude decides which tools to use and in what order, often chaining several.

Two things help:

Be specific about the target. “Update the pricing page” is ambiguous. “Update the pricing page, post ID 128” is not.

Let it read before it writes. Agents produce noticeably better results when they inspect existing structure first. Asking it to “match the styling used elsewhere on the page” prompts exactly that.

Connecting Claude Code — full setup walkthrough
Connecting Claude Desktop — including the bundle
OAuth sign-in — connecting without pasting credentials
No tools appearing — the longer troubleshooting list
The MCP servers worth knowing — what to connect