Connect Your First MCP Server

Learning Objectives

By the end of this lesson, you will be able to:

• Install and configure a real MCP server in Claude Desktop
• Verify that a server connected successfully and see its tools appear
• Use a connected server's tools and resources in a real conversation
• Troubleshoot the most common connection problems

Prerequisites

• Completed: Understanding Context Components
• Claude Desktop installed on your computer
• Comfort opening a text file and editing JSON (we'll walk through every step)

What We're Building

In the last lesson, you learned that every MCP server exposes some combination of Tools, Resources, and Prompts. Now you'll connect one for real. We'll start with the filesystem server - one of the simplest official MCP servers, maintained directly under the modelcontextprotocol project - because it needs no account, no API key, and no sign-up. It just needs permission to read a folder on your computer.

Once you've got that working, we'll also look at connecting GitHub's official MCP server, which runs as a local Docker container authenticated with a personal access token instead of an npm package, so you can see both connection patterns in action.

Step 1: Locate Your Claude Desktop Config File

Claude Desktop reads its MCP server configuration from a JSON file. The location depends on your operating system:

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

If the file doesn't exist yet, open Claude Desktop, go to Settings → Developer → Edit Config, which will create it for you and open the folder in your file browser.

Step 2: Add the Filesystem Server

Open claude_desktop_config.json in a text editor and add the following, replacing the path with a real folder on your machine that you're comfortable letting Claude read (for example, a folder of notes or a practice project - not your entire home directory):

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

What this means:

• "filesystem" is just a label - it's how this server shows up in Claude's UI.
• "command": "npx" tells Claude how to launch the server (this uses Node.js's package runner, which downloads and runs the server on demand).
• The last argument is the one folder this server is allowed to touch. MCP servers are scoped deliberately - the filesystem server can't read anything outside that folder.

If the file already has other servers configured, add "filesystem" as another entry inside the existing "mcpServers" object rather than replacing it.

Step 3: Restart Claude Desktop

Quit Claude Desktop completely (not just close the window) and reopen it. MCP servers are launched when the app starts, so a fresh launch is required to pick up config changes.

Step 4: Verify the Connection

Look for a small tools/plug icon near the message input box, or check Settings → Developer, where connected servers are listed with a status indicator. Click into the filesystem server's entry and you should see its available tools listed - things like read_text_file, write_file, and list_directory. This is capability discovery in action: Claude asked the server "what do you have?" and the server answered with its tool list.

If you don't see the server listed, jump to the Troubleshooting section below before continuing.

Step 5: Use It in a Real Conversation

Open a new chat and try something like:

You: "What files are in my mcp-practice folder?"

Claude will call the filesystem server's list_directory tool, get back the actual contents of that folder, and answer using real data - not a guess. Try a follow-up:

You: "Read notes.md and summarize the key points"

Claude calls read_text_file, retrieves the file's contents as a Resource, and summarizes what's actually in it. You've now used both a Tool (read_text_file/list_directory) and seen how a server surfaces data as a Resource, connected end-to-end.

Step 6: Connect a Second Server (GitHub, Local)

Now let's connect a server that uses the other common pattern: a separate local process alongside the filesystem server. GitHub's official MCP server also ships as a hosted, remote endpoint, but that endpoint is restricted to GitHub Copilot integrations (VS Code, JetBrains, and similar) and rejects connections from third-party clients like Claude Desktop — so for Claude Desktop, run it locally via Docker instead. Create a personal access token first, then add it to your config:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents/mcp-practice"]
    },
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-pat"
      }
    }
  }
}

Restart Claude Desktop again. This time, when you open a chat and try to use a GitHub-related tool for the first time, it'll use the token from your config directly (no browser sign-in step, since this is a local server rather than a hosted OAuth one). Once configured, try:

You: "What are the five most recently opened issues in my repo?"

Claude calls the GitHub server's tools to fetch live issue data and reports back.

Two connection patterns, one protocol: notice that from Claude's side, using the filesystem server and the GitHub server feels identical - ask a question, Claude picks the right tool, you get an answer. The difference (an npx-run process vs. a Docker-run process) is invisible to the conversation. That consistency is the whole point of MCP.

Troubleshooting

Server doesn't appear in the list

• Confirm the JSON is valid - a missing comma or brace will silently break the whole file. Paste it into a JSON validator if you're unsure.
• Make sure you fully quit and reopened Claude Desktop, not just closed the window.

Server appears but shows an error status

• For the filesystem server, double-check the folder path exists and is spelled correctly.
• Make sure npx is available - it ships with Node.js, so install Node if you haven't already.

Claude says it can't find a tool it should have

• Open Settings → Developer and confirm the server's tool list actually loaded. If it's empty, the server may have failed to start - check the logs linked from that same settings screen.

GitHub server appears but tool calls fail

• Confirm your personal access token is valid and hasn't expired, and that it has the scopes the tool you're calling needs (e.g. repo for reading issues).
• Confirm Docker is installed and running - the docker run command in your config needs a working Docker daemon to launch the server.
• If it still fails, remove the github entry, restart Claude Desktop, then re-add it and try again.

Hands-On Exercise: Add a Third Server

Your task: Pick one more official or community server relevant to something you use - for example, a Slack, Postgres, Notion, or Linear server - and:

1. Find its current setup instructions (search modelcontextprotocol.io or the vendor's own docs, since exact install steps vary by server).
2. Add it to your claude_desktop_config.json alongside the servers you already have.
3. Restart Claude Desktop and confirm it shows up with a healthy status.
4. Ask Claude a question that requires that server's data, and confirm the answer reflects real information instead of a guess.

Try it yourself - working through one unfamiliar server's setup instructions is the best way to build confidence that you can add any MCP server, not just the two from this lesson.

Knowledge Check

1. What's the difference between how the filesystem server and the GitHub server are configured, and why does that difference exist?
2. Why does the filesystem server only need one folder path as an argument, rather than access to your whole computer?
3. What should you check first if a newly added server doesn't appear in Claude Desktop after a restart?
4. When Claude answers "what files are in this folder," which MCP capability is doing the work - a Tool, a Resource, or a Prompt?

What's Next?

You've connected and used two real MCP servers. In the next lesson, we'll zoom out and look at how teams put multiple MCP servers to work together in real workflows - engineering agents that use GitHub, Linear, and Slack together; research agents that pull from the web, PDFs, and databases; and more.

Ready to see it at scale? Continue to Real-World MCP Applications →

---

Quick Reference: Connecting a Server

1. Find the server - official docs, modelcontextprotocol.io, or the vendor's own site
2. Open your config - claude_desktop_config.json (via Settings → Developer → Edit Config)
3. Add an entry - local servers use command/args; hosted servers use url
4. Restart Claude Desktop - MCP servers load at startup
5. Verify - check Settings → Developer for a healthy status and tool list
6. Use it - ask a question that requires the server's tools or data

Remember: Every server, no matter how it's configured, is discovered and used the same way once connected - that consistency is what makes MCP worth learning once.