How to Connect Your First MCP Server

// In plain English

An MCP server is a small program that wraps a capability — your local files, a GitHub account, a database — and exposes it to any AI app over the Model Context Protocol. Once connected, the AI app can discover every tool the server offers and call them automatically during a conversation.

The best analogy is a printer driver. When you plug in a new printer, you install a small driver that tells your operating system what the printer can do. After that, every app on your computer can print without knowing anything about the hardware. An MCP server is the driver; the AI host (Claude Desktop, VS Code, Cursor) is the operating system; the tools inside the server are the printer commands.

This article walks you through the connection side — you pick a server that already exists, point your AI app at it with a few lines of JSON, restart, and start calling its tools. If you want to build a server from scratch instead, see the companion article on building MCP servers.

// Why connecting an MCP server matters

AI models are powerful reasoners that are, by default, completely isolated. They cannot read your files, query your calendar, hit a live API, or open a pull request. Every useful thing a model does outside pure text generation requires a bridge to the real world — and MCP is now the standard way to build that bridge.

Before MCP, every AI app vendor built its own connector for each service. Connecting the same GitHub account to three different AI tools meant setting up three separate integrations. MCP collapses that: one server, every compatible host. You configure the filesystem server once and it works in Claude Desktop, VS Code Copilot, Cursor, and any other host that speaks MCP.

For a builder, this matters because the gap between a demo and a useful agent is almost always the tools. A model that can actually read your codebase, check a live API, or write to a file is orders of magnitude more useful than one that cannot. Connecting your first MCP server is the fastest way to feel that difference.

• Immediate capability boost — the model gains real tools without you writing any server code
• Reusable across hosts — one config works wherever MCP is supported
• Community ecosystem — hundreds of pre-built servers exist for GitHub, Slack, Postgres, Google Drive, and more
• Foundation for agents — every agent that does real work needs at least one MCP server behind it

// How the connection works

When you add an MCP server entry to your host's config file, the host launches the server as a child process (for local servers) or opens an HTTP connection (for remote servers). The two sides speak JSON-RPC 2.0 — a simple message format where every request has an id, a method, and optional params, and every response echoes the id back with a result or error.

The handshake is automatic. On startup the host sends an initialize request; the server replies with the protocol version it supports and a list of its capabilities. The host then sends tools/list to discover every tool the server exposes — name, description, and JSON Schema for the parameters. From that point on the model can call any tool by name whenever it decides one is needed.

For local servers the default transport is stdio — the host writes JSON-RPC messages to the server's standard input and reads responses from standard output. This is why the config asks for a command and args: the host needs to know how to start the process. For remote servers the transport switches to HTTP with Server-Sent Events or Streamable HTTP, and the config provides a url instead.

// Step-by-step: connecting the filesystem server to Claude Desktop

The filesystem MCP server (@modelcontextprotocol/server-filesystem) is the standard first server to connect. It lets Claude read directory listings, read file contents, and write files — all scoped to whichever folders you allow. It ships as an npm package, so it runs with npx and needs no global install.

1. Prerequisites

• Claude Desktop installed and signed in (download from claude.ai/download)
• Node.js 18+ installed — node --version in a terminal should print v18 or higher
• A text editor that can edit JSON files (Notepad, VS Code, anything)

2. Open the config file

In Claude Desktop, open Settings (gear icon), go to the Developer tab, and click Edit Config. This opens your claude_desktop_config.json file in your default text editor. The file location differs by OS:

3. Add the server entry

Replace the entire file contents with the JSON below (or merge the mcpServers block into your existing config if you already have other servers). Swap /Users/yourname/projects for an actual folder you want Claude to access:

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

On Windows, use a Windows-style path such as C:\\Users\\yourname\\projects. You can list multiple folders by appending more path arguments after the first one — each becomes an allowed root the server can access.

4. Restart Claude Desktop completely

Save the config file, then fully quit Claude Desktop — do not just close the window. On macOS use Cmd+Q or right-click the dock icon and choose Quit. On Windows, right-click the system tray icon and choose Exit. Then reopen it. Claude Desktop only reads the config on startup.

5. Verify the connection

After restarting, look for a hammer icon (tools) in the bottom-left of the chat input box. Click it to see a list of connected MCP tools — you should see entries like list_directory, read_file, and write_file under the filesystem server. If the icon is absent or the server shows an error badge, check the troubleshooting section below.

6. Call your first tool

Type a prompt that naturally requires the filesystem: "List the files in my projects folder." Claude will call list_directory automatically, show you the result, and continue the conversation with that context in place. You just watched the model use an MCP tool.

// Other hosts and popular servers

Claude Desktop is the most common starting point, but MCP is supported across several hosts. The config structure is nearly identical in each — you are always providing a server name, a command/args (or url), and optional environment variables.

VS Code (GitHub Copilot Chat)

Create a file at .vscode/mcp.json in your workspace (or edit the global user mcp.json). The key difference is that VS Code uses "servers" instead of "mcpServers" at the top level:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Passing API keys securely

Many servers (GitHub, Slack, Notion) need an API token. Pass it in the env block of the server config — never hardcode it in args where it might end up in logs:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_yourtoken"
      }
    }
  }
}

Popular ready-to-use servers

Python-based servers use uvx instead of npx as the command. Install uv first (pip install uv or the official install script), then use "command": "uvx" with the PyPI package name in args.

// Troubleshooting common connection problems

Most MCP connection failures fall into one of four categories: the binary cannot be found, the JSON config has a syntax error, an environment variable is missing, or the host was not fully restarted. Work through this checklist before diving deeper.

Server shows an error badge or does not appear

1. Check the JSON syntax. Open the config file and paste it into jsonlint.com. Even a single trailing comma causes a silent failure.
2. Verify Node.js is in PATH. Open a new terminal (not one already open before install) and run node --version. On macOS with nvm, the GUI app may not inherit your shell PATH — use the full path to npx instead, e.g. /usr/local/bin/npx.
3. Fully quit and restart the host. Closing the window is not enough — the process must exit entirely before it re-reads the config.
4. Run the server command manually. Copy the command and args from your config and run them in a terminal. Any error printed to the terminal is the real error — not a vague badge.

Server connects but no tools appear

The server started successfully but the tools/list handshake returned nothing. This usually means a missing API key (the server authenticated but has no scope), a version mismatch between the server and the host's protocol version, or a server that only exposes resources and prompts (not tools). Check the server's README for required environment variables and minimum SDK versions.

"spawn ENOENT" error

ENOENT means the host could not find the executable named in command. On macOS this is almost always a PATH problem: the GUI app does not run your .zshrc or .bashrc, so npx is not on its PATH. Fix: run which npx in your terminal and use that full path (e.g. /opt/homebrew/bin/npx) in your config.

// Going deeper

Once you have a server running and tools responding, a few natural next steps open up:

Add more servers

The mcpServers object accepts as many entries as you like. Each key is the server's display name in the host UI; each value is its config. Servers run in parallel as separate processes and do not interfere with each other. Add a GitHub server, a database server, and a web-fetch server alongside your filesystem server and the model gains all of them at once.

Remote (HTTP) servers

Local stdio servers run on your machine and are private. Remote HTTP servers are hosted services any client can reach over a URL. Many SaaS vendors now publish public MCP endpoints. For these you provide a url key instead of command/args, and the host connects over HTTP rather than spawning a process. VS Code and Cursor support both; Claude Desktop (as of mid-2026) supports remote servers through the Extensions directory.

Resources and prompts

Tools are the most visible MCP primitive but not the only one. Resources are file-like data the model can read — think documentation pages, database rows, or config files exposed as MCP URIs rather than tool calls. Prompts are parameterized templates the host can inject at conversation start. Many servers expose all three; the host's UI shows each type separately.

Building your own server

Every internal system, proprietary API, or custom workflow that does not have a published MCP server is an opportunity to write one. The official Python SDK (mcp on PyPI) and TypeScript SDK (@modelcontextprotocol/sdk on npm) make it straightforward — you define tools as decorated functions, call server.run(), and the SDK handles all the JSON-RPC machinery. The companion article on building MCP servers walks through this in detail.

Security considerations

Every MCP server you connect expands the surface the model can act on. A few rules of thumb: scope filesystem servers to the minimum folders the model needs, not your entire home directory; rotate API tokens regularly and store them in env blocks rather than args; review what each server's tools actually do before connecting it — a server that can delete files or push to production can cause real damage if the model misunderstands a request.