How Do You Set Up an MCP Server?

Set up an MCP server in three steps: add the server’s entry to your AI client’s configuration, restart the client, and verify the server’s tools appear. The Model Context Protocol (MCP) is the open standard Anthropic created in November 2024. Every application that supports it, from Claude Desktop to Cursor to the Gemini CLI, uses this same setup pattern.

The pattern is universal. The details are not. Eight major clients keep their configuration in eight different places. Three different root keys name the server list, and one client uses TOML instead of JSON. Restart behavior ranges from a full application quit to a refresh button to nothing at all. Those differences cause most first-install failures, and this page maps all of them. One distinction before the steps: setup means connecting an existing server. Writing a new server is a build task, and the build guides cover it separately.

Below: the three steps with an annotated template config, the configuration path and root key for every major client, the per-client tutorial directory, verification, and the deployment guides. The paths and keys come from each client’s current documentation and real installs, checked June 2026.

What MCP is and how it works 

What Are the Three Steps of Every MCP Setup?

Every MCP setup follows the same sequence: install the runtime the server needs, add the server’s entry to the client’s config, then restart the client and verify the tools appear.

1. Install the runtime. Local servers run as processes on your machine. Node.js servers launch through npx, and Python servers launch through uvx. The package manager downloads the server on first run, so a missing runtime is the failure that happens before anything else can.
2. Add the config entry. The config file tells the client what to launch. Each entry specifies three things: the command to execute, the arguments to pass, and the environment variables (tokens, keys, paths) the server needs.
3. Restart and verify. The client launches its configured servers at startup, so the new entry takes effect only after a restart. Then confirm the server’s tools appear in the client’s tool list.

Here is the universal template, shown in Claude Desktop’s format. The structure transfers to every JSON-based client; only the file location and root key change:

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

Three annotations make this entry safe and portable. The server name ("filesystem") is yours to choose and becomes the label in the tool list. The final argument is the only directory this server can touch. Point it at one project folder, never your home directory. Servers that need a token take an "env" object alongside "args". The same minimum-scope rule applies to every credential you put there.

The steps stay constant. The file you put that entry in does not, and that is where setups break.

Where Does Each Client Keep Its MCP Configuration?

Eight major clients use eight different config locations, three different root keys, and three different restart behaviors. This table is the cross-client map.

Four traps in that table cause the bulk of failed first installs:

• VS Code names the key servers, not mcpServers. A Claude Desktop block pasted into .vscode/mcp.json fails silently until the key changes (VS Code MCP documentation, April 2026).
• Codex CLI uses TOML, not JSON. The server list lives under [mcp_servers] in ~/.codex/config.toml, with TOML syntax throughout. Pasting JSON into it produces a parse error.
• Windsurf never creates its config file. mcp_config.json does not exist until you create it (MCPFind, April 2026). Windsurf compensates elsewhere: a refresh button replaces restarts, tools toggle individually, and ${env:VAR} plus ${file:path} interpolation keeps secrets out of the file (Windsurf Cascade documentation).
• Windows moves every path. %APPDATA%\Claude\ replaces the macOS Library path, %USERPROFILE% replaces ~, and a client running in native Windows cannot see runtimes installed inside WSL.

JetBrains IDEs (IntelliJ, Rider) sit outside the table for now: they ship built-in MCP configuration under Settings, Tools, MCP Server, with no separate config file to edit.

One wrong path circulates in AI-generated answers: ~/.claude/claude_desktop_config.json, which fuses Claude Code’s directory with Claude Desktop’s filename. The table above carries the verified locations, checked against each client’s documentation in June 2026.

Which MCP Setup Guide Do You Need?

Pick the guide for the client you use. Each walkthrough below covers the full path: install, exact working config, verification, and the errors that client throws, with fixes merged in.

Claude Desktop

The canonical first MCP setup. Edit claude_desktop_config.json (or use Settings → Developer → Edit Config), add the entry, then fully quit and reopen; closing the window does not reload the config. MCP access requires a Claude Pro subscription as of March 2026.

Cursor

Project-scoped config that travels with the repository. Cursor reads .cursor/mcp.json from the project root, so a committed config gives the whole team the same servers.

VS Code

MCP through GitHub Copilot Chat, with the renamed root key. Use the “MCP: Add Server” command palette flow for a guided install, or edit .vscode/mcp.json directly with the servers key.

Claude Code

One command instead of a config file. claude mcp add <name> <command> registers a server from the terminal, and Tool Search loads definitions on demand instead of all at once.

ChatGPT

No config file anywhere. ChatGPT connects to remote MCP servers through its Connectors UI, added by OpenAI in April 2025; local stdio servers are not part of the flow.

Gemini CLI

settings.json plus an allowlist. Servers live under mcpServers in ~/.gemini/settings.json, the gemini mcp add command writes entries for you, and the mcp.allowed list restricts which configured servers are permitted to connect (Gemini CLI documentation, April 2026).

Codex CLI

The TOML one. OpenAI’s Codex CLI configures servers under [mcp_servers] in ~/.codex/config.toml, the only major client that skips JSON entirely.

Windsurf

Refresh instead of restart. Windsurf reads ~/.codeium/windsurf/mcp_config.json, exposes a refresh button in the Cascade panel, and lets you toggle individual tools per server.

Config file reference

Every field, every client, every malformed-field error. The single reference for command, args, env, serverUrl, scopes, and path locations across operating systems: MCP config file reference.

Troubleshooting

Real error strings mapped to root causes. Server not showing up, connection failed, tool not invoked: the cross-client diagnostic page, ordered by how often each failure happens: fix MCP connection errors.

Windows

The platform with its own failure class. Path differences, %APPDATA% locations, and the WSL-versus-native runtime mismatch that breaks npx silently: MCP setup on Windows.

How Do You Verify an MCP Server Is Working?

Verify a setup by checking the client’s tool list, then running one test call against the new server. Every client surfaces connected servers somewhere visible: Claude Desktop shows an anvil or plug-in icon in the chat box once tools register, Cursor marks each connected server with a green dot in its MCP settings, Windsurf lists servers in the Cascade panel, and the Gemini CLI prints them with the /mcp command.

A clean tool list is half the proof. The other half is one real call. Ask the model to use the new server on a trivial task, such as listing the files in the configured directory. A server can register its tools and still fail on execution when a token lacks scope or a path does not exist. Each registered server also spends part of the context window on tool definitions before any call happens, which is why connecting only the servers the current task needs is the default discipline.

When the tool list stays empty, triage in this order: the config was not reloaded (restart behavior in the table above), the runtime is missing (npx or uvx not found), or the credential is wrong (server connects, every call fails).

A local server on a laptop covers one developer. The deployment guides cover everything past that point: containers, hosted endpoints, and models that never leave your machine.

How Do You Deploy MCP Servers Beyond Your Laptop?

Four deployment paths extend MCP past a local process: containers, edge hosting, remote endpoints with OAuth, and local models. Maintenance recency matters double here, because a deployed server that falls behind the specification fails for every user at once.

• Docker. Run servers as containers for isolation and clean dependency management; the GitHub server already ships this way. Prerequisites, compose patterns, and the failure modes: run MCP servers in Docker.
• Cloudflare. Deploy a server to Cloudflare’s edge so it runs without your machine: deploy MCP servers on Cloudflare.
• Remote MCP servers. Host a server behind streamable HTTP with OAuth 2.1 so any client connects by URL; this is the same architecture the hosted GitHub and Linear endpoints use, also called hosted or remote servers: host remote MCP servers.
• Local LLMs. Connect MCP servers to Ollama and other local models through bridge tools, keeping the whole loop on your hardware: use MCP with local LLMs.

When Do You Skip Manual Setup Entirely?

Skip the config file when a one-click path exists for your client and server. Manual JSON editing is the universal route, not the mandatory one, and the no-config options have grown into a real alternative:

• Desktop Extensions (.mcpb) install a server into Claude Desktop with one click and no editor, introduced in early 2026 (Claude Help Center, March 2026). Claude Desktop also ships a Connectors panel and an extensions marketplace for the same purpose.
• CLI installers write the config entry for you. fastmcp install claude-desktop server.py registers a Python server in one command (FastMCP 2.10.3+, gofastmcp.com), and npx -y @smithery/cli install <server> --client claude does the same for Smithery-listed servers.
• Guided flows replace hand-editing in two clients: VS Code’s “MCP: Add Server” palette command walks through the entry, and gemini extensions install <url> registers a packaged server in one line.
• Remote servers reduce setup to pasting a URL. A hosted endpoint with OAuth needs no runtime, no Docker, and no token in a file.

The one-click paths trade control for speed: no toolset flags, no custom arguments, no environment tweaks. Take them when the defaults fit, and drop to the config file when they stop fitting. Either way the verification step stays the same.

MCP Setup Questions

What Is an MCP Setup?

An MCP setup is the configuration that connects an AI client to one or more MCP servers: a config entry naming each server, the credentials it needs, and a restart to load it. The annotated template at the top of this page is a complete minimal example.

What Is the Easiest Way to Set Up an MCP Server?

The easiest path is a one-click install: a Desktop Extension in Claude Desktop or the “MCP: Add Server” flow in VS Code. The easiest manual path is the Filesystem server through npx, because it needs no token and fails loudly when something is wrong. Both take under five minutes.

How Long Does MCP Setup Take?

A first setup takes 2 to 5 minutes per client: one config entry, one restart, one verification. Repeat installs take under a minute, because the runtime exists and the pattern is known. Docker-based servers add the one-time Docker install on top.

Do You Need to Know How to Code to Set Up MCP?

No. Setup means editing a JSON or TOML file or clicking through an install flow, not writing code. Anyone comfortable opening a text file can complete it. Using MCP after setup requires no technical skill at all: the user types plain language, and the model decides which tools to call.

Is Setting Up an MCP Server the Same as Building One?

No. Setup connects an existing server to your client. Building means writing a new server with an SDK. The two tasks share nothing past the config entry. The SDK quickstarts, FastMCP, and testing live in the build guides.

Is MCP Setup Different on Windows?

Yes, in two ways: every config path moves, and WSL splits the runtime from the client. %APPDATA% and %USERPROFILE% replace the macOS and Linux paths, and a client in native Windows cannot launch a server whose runtime lives inside WSL.

Every page in this directory ends at the same three steps this one began with: a config entry, a restart, a verified tool list. Pick the client above and run them.