Connecting Your First MCP Server

Introduction

Knowing what MCP is gets you halfway there. The other half is actually connecting a server and watching it work. This lesson is hands-on: we walk through adding a real MCP server to Claude Code, explain every field in the config, and describe what happens when the connection is established.

By the end, you will have connected your first server and understand the mechanics well enough to add any server you encounter.

Core Concept

The Config File Is Your Wiring

MCP clients discover servers through a configuration file. For Claude Code, that file is ~/.claude.json at the global level (applies to all projects) or .mcp.json at the root of a specific project folder (scoped to that project only — and designed to be checked into version control so the whole team shares it). You can also let Claude Code write these files for you with claude mcp add --scope user or claude mcp add --scope project.

The configuration has one key per server, each with enough information for the client to launch and connect to the server process.

Two Common Transport Types

Most servers you will encounter use one of two transports:

stdio — the client spawns the server as a child process and communicates over standard input/output. This is the most common type. The server lives and dies with the client session.

HTTP (Streamable HTTP) — the server runs independently at a URL, and the client connects to it over HTTP. Use this for servers that need to persist (like ones backed by a database) or servers you want to share across multiple clients. Older docs and configs call this transport SSE (Server-Sent Events) — the original HTTP+SSE transport was deprecated in favor of Streamable HTTP, but you will still see the old name around.

For beginners, start with stdio. It requires no infrastructure — just a command the client can run.

Practical Application

Step 1: Choose a Server

We'll use a filesystem server as the example — it lets the AI read and write files within a directory you specify. It is one of the most widely-used beginner servers.

The package is @modelcontextprotocol/server-filesystem. You need Node.js installed.

Step 2: Add the Config

Open ~/.claude.json in your editor. If the file doesn't exist, create it. Add the mcpServers block:

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

Let's break down every field:

• "filesystem" — the name you give this server. This is how you refer to it in logs and error messages. Pick something descriptive.
• "command" — the executable to run. Here it is npx, which can run npm packages without installing them globally.
• "args" — command-line arguments. -y tells npx to skip the install prompt. The package name is the server. The final argument is the root directory the server is allowed to access.

Step 3: Restart Your Client

Config changes take effect on the next client launch. Close Claude Code and reopen it. During startup, Claude Code reads the config, spawns the filesystem server process, and establishes the stdio connection.

Step 4: Verify the Connection

In your first message, ask the AI: "What MCP tools do you have available?" or "List your connected servers." A working connection will show the server name and its available tools.

For the filesystem server, you should see tools like read_file, write_file, list_directory, and search_files.

A Second Example: Web Search via npx

Here is a second server added alongside the filesystem one — the grok-search-mcp server (X/Twitter search):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    },
    "web-search": {
      "command": "npx",
      "args": ["-y", "grok-search-mcp"]
    }
  }
}

Both servers are now available in the same session. The AI picks whichever one is relevant to each request.

Adding Environment Variables

Some servers need API keys. Pass them via the env key:

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "grok-search-mcp"],
      "env": {
        "GROK_API_KEY": "your-key-here"
      }
    }
  }
}

The env object merges with the client's environment — the server process sees these variables as regular environment variables.

Common Mistakes

Editing the config while the client is running. The client reads config at startup. Changes made to the file while the client is open have no effect until you restart.

Forgetting the directory argument for filesystem servers. The filesystem server requires at least one allowed root path. Without it, the server starts but refuses all file operations.

Using the wrong config file scope. (~/.claude.json) applies everywhere. (.mcp.json at the project root) only applies in that project's directory. If your server isn't showing up, check that you edited the right file.

Not having Node.js installed when using npx. The npx command requires Node.js. Run node --version in your terminal first. If it fails, install Node.js before continuing.

Summary

• MCP servers are configured in ~/.claude.json (global) or .mcp.json at the project root (project-scoped)
• Each server entry needs a command, an args array, and optionally an env object for API keys
• stdio servers are spawned as child processes when the client starts; no infrastructure required
• Restart your client after any config change — there is no hot reload
• You can run multiple servers simultaneously; the AI picks the right one per task

What's Next

You have a server connected. But not all tools are equal — some tools read data, others make permanent changes. The next lesson covers the single most important safety distinction in MCP: read tools versus write tools, and why you should always review write actions before approving them.