First Contact: Using an MCP Server in Claude Code

Capsule description

You've understood the M×N problem, the MCP solution, and the current ecosystem. Now it's time to see MCP in action. In this capsule you're going to configure an existing MCP Server in Claude Code and use it to solve real tasks. You're not going to build a server yet (that comes in modules 3-6) — you're going to be the user of one.

This first contact is crucial. Seeing an MCP Server working — where Claude Code uses external tools as if they were native — anchors everything conceptual in something tangible. When the server responds to your request, the mental model of MCP will stop being abstract.

Preparation: what you need

Before starting, verify that you have everything ready:

# 1. Claude Code installed and up to date
claude --version
# Should show a recent version

# 2. Node.js installed (required for TypeScript servers)
node --version
# Should be v18+

# 3. npm available
npm --version

# 4. npx available (comes with npm)
npx --version

Verification: If all 4 commands return versions, you're ready. If any of them fails, install it before continuing.

If something is missing:

# Install Node.js (if you don't have it)
# macOS with Homebrew:
brew install node

# Verify everything got installed
node --version && npm --version && npx --version

Prepare a test directory

For the examples to work, you need a directory with files. You can use an existing one or create a test one:

# Create a test directory with content
mkdir -p ~/mcp-playground/src
mkdir -p ~/mcp-playground/docs

echo "# My MCP Project" > ~/mcp-playground/README.md
echo '{"name": "mcp-playground", "version": "1.0.0", "dependencies": {"express": "^4.18.0", "typescript": "^5.0.0"}}' > ~/mcp-playground/package.json
echo "console.log('Hello MCP')" > ~/mcp-playground/src/index.js
echo "// TODO: implement user authentication" > ~/mcp-playground/src/auth.js
echo "// TODO: add error handling" > ~/mcp-playground/src/utils.js
echo "# Project notes" > ~/mcp-playground/docs/notes.md
echo "def main(): pass  # TODO: implement" > ~/mcp-playground/src/app.py

Verify that it was created correctly:

ls -la ~/mcp-playground/
# You should see: README.md, package.json, src/, docs/

ls -la ~/mcp-playground/src/
# You should see: index.js, auth.js, utils.js, app.py

The MCP Server we're going to use: Filesystem

We're going to configure the official Filesystem MCP Server. It's ideal as a first contact because:

• ✅ It's an official Anthropic server (trustworthy, well documented)
• ✅ It doesn't require API keys or external accounts
• ✅ It works with your local filesystem (immediate results)
• ✅ It exposes clear, easy-to-understand tools
• ✅ You can verify the results by looking at your files directly

What the Filesystem Server can do

Available tools:
├── read_file          → Reads a file's contents
├── read_multiple_files → Reads several files at once
├── write_file         → Writes contents to a file
├── edit_file          → Edits an existing file
├── create_directory   → Creates a folder
├── list_directory     → Lists files and folders
├── directory_tree     → Shows the tree structure
├── move_file          → Moves or renames a file
├── search_files       → Searches files by pattern
├── get_file_info      → File metadata
└── list_allowed_directories → Shows the allowed directories

Step 1: Configure the MCP Server in Claude Code

Option A: Configuration via command (recommended)

Claude Code lets you add MCP servers from the terminal:

# Add the Filesystem MCP Server
# Replace /Users/your-user/mcp-playground with your real directory
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /Users/your-user/mcp-playground

Breakdown of the command:

claude mcp add          # Command to add an MCP server
  filesystem            # Name you give the server (you can choose any)
  -s user               # Scope: "user" (available in all your sessions)
  --                    # Separator between claude args and server args
  npx -y                # Runs the package without installing it globally
  @modelcontextprotocol/server-filesystem  # Official server package
  /Users/your-user/mcp-playground          # Directory it will have access to

Immediate verification of step 1

Verify that the server was registered correctly:

# List the configured MCP servers
claude mcp list

You should see something like:

User-scoped MCP servers:
  filesystem: npx -y @modelcontextprotocol/server-filesystem /Users/your-user/mcp-playground

If you see your server listed, the configuration was successful.

Option B: Manual configuration via JSON

If you prefer to configure it manually, edit the configuration file:

# Open the Claude Code configuration file
# The location depends on your system:

# macOS/Linux:
cat ~/.claude/settings.json

Add the MCP server configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/your-user/mcp-playground"
      ]
    }
  }
}

Step 2: Verify that the server is connected

Open a new Claude Code session:

# Start Claude Code
claude

Verify that the MCP server loaded correctly:

# Inside Claude Code, use the /mcp command
/mcp

You should see something like:

MCP Servers:
  filesystem: connected
    Tools:
      - read_file
      - write_file
      - list_directory
      - search_files
      - ...

Verification checklist

• ✅ The server appears with status connected
• ✅ The available tools are listed
• ✅ The name matches the one you configured (filesystem)

If you see connected, your MCP server is working. If not, go to the Troubleshooting section at the end.

Step 3: Use the MCP Server

Now comes the interesting part. With the server connected, you can ask Claude Code to use its tools. Claude Code will automatically decide when to use the MCP Server's tools.

Example 1: Explore a directory

You: "What files are in my projects directory?"

Claude Code is going to:

1. Identify that it has the list_directory tool available
2. Invoke the tool with your directory's path
3. Receive the list of files from the MCP Server
4. Present you the results

Expected output:

Here are the files in /Users/your-user/mcp-playground:

📁 src/
📁 docs/
📄 README.md
📄 package.json

Verify: Open your terminal separately and run ls ~/mcp-playground. Does it match what Claude Code showed? It should be identical.

Example 2: Read a file

You: "Read the package.json file and tell me what dependencies I have"

Claude Code is going to:

1. Use read_file with the path to the file
2. Receive the file's contents
3. Process and analyze the contents

Verify: Open ~/mcp-playground/package.json in your editor. Is the content that Claude Code read correct?

Example 3: Search for files

You: "Search for all .js files in my projects"

Claude Code is going to:

1. Use search_files with the pattern *.js
2. Receive the list of JavaScript files
3. Present you the organized results

Verify: Run find ~/mcp-playground -name "*.js" in your terminal. Do the results match?

Example 4: Create a file

You: "Create a file called ideas.md with a list of 5 ideas for MCP projects"

Claude Code is going to:

1. Generate the content based on your request
2. Use write_file to create the file
3. Confirm that the file was created

Note: Claude Code will ask you for confirmation before writing files, for safety.

Verify: After Claude Code confirms the creation, run cat ~/mcp-playground/ideas.md in your terminal. Does the file exist and have the correct content?

Example 5: Directory structure

You: "Show me the complete structure of the directory"

Claude Code is going to:

1. Use directory_tree on the configured directory
2. Present the structure in tree format

Verify: Run tree ~/mcp-playground (if you have tree installed) or find ~/mcp-playground -type f to compare.

Step 4: Observe the MCP flow

While you use the server, pay attention to what happens. When Claude Code decides to use a tool from the MCP Server, you'll see something like:

⏳ Using MCP tool: filesystem.read_file
   Path: /Users/your-user/mcp-playground/README.md

This shows you:

• Which tool is used — read_file from the filesystem server
• With what arguments — the path to the file
• That it's automatic — Claude Code decides when to use the tool based on your request

This is MCP in action. The Host (Claude Code) uses the Client (internal) to invoke a Tool on the Server (filesystem), receives the response, and presents it to the user. Exactly the flow you saw in the previous capsule.

What to observe while you use MCP

While you experiment, pay attention to these aspects of the protocol's flow — understanding these details will help you when you build your own servers:

1. Automatic discovery

When Claude Code starts up, it contacts each configured MCP server and asks it "what can you do?" The server responds with its list of capabilities. Notice: when you run /mcp, the list of tools you see is the result of that discovery process. Claude Code doesn't have that information hardcoded — it gets it from the server in real time.

2. Intelligent tool selection

Claude Code doesn't use MCP tools randomly. Notice which requests activate tools and which don't:

"What is MCP?"                    → Does NOT use MCP tools (can answer without them)
"Read my README.md file"          → DOES use read_file
"How many .py files do I have?"   → DOES use search_files or list_directory
"Explain what TypeScript is"      → Does NOT use MCP tools

3. Confirmation of write operations

Notice that Claude Code asks for confirmation before operations that modify files (write_file, edit_file, move_file), but not for read operations (read_file, list_directory). This is a security measure of the Host, not of the protocol.

4. Response format

Notice how Claude Code transforms the server's raw responses into natural language. The server returns JSON (e.g.: {"files": ["a.js", "b.py"]}), but you see a human response. The Host does that transformation, not the server.

5. Latency

Notice that the first time you use a tool it may take a couple of seconds (because npx needs to download the package). Subsequent calls are faster. In the troubleshooting section you'll see how to solve this if it bothers you.

Step 5 (Optional): Configure a second MCP Server

To experiment with multiple simultaneous servers, you can add another one. The Memory Server is a good option:

# Add the Memory MCP Server
claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory

Verify both servers

# List the configured servers
claude mcp list
# You should see: filesystem and memory

# In Claude Code, verify the connections
/mcp
# You should see both as "connected"

Now Claude Code has access to two MCP servers:

• filesystem — for file operations
• memory — for storing and retrieving persistent information

Try:

You: "Remember that my favorite language is Python and that I'm
     learning MCP"
→ Claude Code uses memory.store_memory()

You: "What's my favorite language?"
→ Claude Code uses memory.retrieve_memory()
→ Responds: "Your favorite language is Python"

This demonstrates the composable principle — multiple MCP servers working together, each with its specific capabilities. Claude Code chooses which server to use based on your request.

Combining both servers

Try a request that uses both servers:

You: "Read my README.md file and remember it for future sessions"
→ Claude Code uses filesystem.read_file() to read the content
→ Then uses memory.store_memory() to save it
→ "I read your README.md and saved it in memory."

Exercises

Exercise 1: Configure a third MCP Server (Easy)

Configure the Fetch MCP Server (to make HTTP requests) and verify that it works:

claude mcp add fetch -s user -- npx -y @modelcontextprotocol/server-fetch

Exercise 2: Search for TODOs in your code (Medium)

Using the Filesystem MCP Server, ask Claude Code to search for all the TODO comments in the files of your test directory.

"Search all the files in my directory and show me the ones that contain
the word 'TODO'. For each one, show me the line with the TODO."

I found TODOs in the following files:

📄 src/auth.js (line 1):
   // TODO: implement user authentication

📄 src/utils.js (line 1):
   // TODO: add error handling

📄 src/app.py (line 1):
   def main(): pass  # TODO: implement

Exercise 3: Create a directory structure (Medium)

Ask Claude Code to create a directory structure for a new project inside your playground:

Create inside my directory a folder called "new-project"
with the following structure:
- src/
  - index.ts
  - config.ts
- tests/
  - index.test.ts
- README.md with the title "New Project MCP"

# Verify that the structure was created
tree ~/mcp-playground/new-project/
# Or if you don't have tree:
find ~/mcp-playground/new-project/ -type f

new-project/
├── README.md
├── src/
│   ├── index.ts
│   └── config.ts
└── tests/
    └── index.test.ts

Exercise 4: Use multiple servers in a flow (Hard)

If you configured the Filesystem and Memory servers, try a flow that uses both:

1. Ask Claude Code to read your package.json
2. To extract the dependencies
3. To remember that information for future sessions

"Read my package.json, extract the dependencies, and remember them
for future sessions. Then confirm what you saved."

"What dependencies does my project have?"
→ Claude Code uses memory.retrieve_memory()
→ "Your project has express ^4.18.0 and typescript ^5.0.0"

Module mini-project: Map M×N vs M+N integrations

Now that you've experimented with MCP, complete this module's mini-project.

Objective

Map 3 real integrations from your day-to-day to the M×N vs M+N model.

Instructions

1. List 3 integrations you use or wish you had:

   • Example: "I want Claude Code to access my PostgreSQL database"
   • Example: "I want Cursor to be able to search my Notion"
   • Example: "I want my AI coding assistant to query the internal documentation"

2. For each one, draw:

   • M×N model: How many custom integrations would you need if you want it to work in 3 different AI hosts?
   • M+N model: How many implementations would you need with MCP?

3. Calculate the savings:

   • Total M×N vs Total M+N
   • Reduction percentage

4. Reflect:

   • Does any of these integrations already exist as an MCP Server?
   • Which would be the most valuable to build as the final project of this guide?

Delivery format

# Module 1 Mini-Project: M×N vs M+N Integrations

## My 3 desired integrations

### 1. [Integration name]
- **Service:** [Which service]
- **AI Hosts where I want it:** [List of hosts]
- **M×N:** [Calculation]
- **M+N:** [Calculation]
- **Does an MCP Server exist?:** [Yes/No/Partial]

### 2. [Integration name]
[...]

### 3. [Integration name]
[...]

## Totals
- **Total M×N:** [Sum]
- **Total M+N:** [Sum]
- **Savings:** [Percentage]

## Reflection
- **Most valuable integration for my final project:** [Which one and why]

# Module 1 Mini-Project: M×N vs M+N Integrations

## My 3 desired integrations

### 1. PostgreSQL Database
- **Service:** PostgreSQL (current project's database)
- **AI Hosts:** Claude Code, Cursor, Windsurf
- **M×N:** 3 hosts × 1 service = 3 custom integrations
- **M+N:** 3 clients + 1 server = 4 implementations (but the clients already exist)
- **Does an MCP Server exist?:** ✅ Yes, official Anthropic server

### 2. Notion Knowledge Base
- **Service:** Notion (team documentation)
- **AI Hosts:** Claude Code, Cursor, Windsurf
- **M×N:** 3 × 1 = 3 custom integrations
- **M+N:** 3 + 1 = 4 (clients already exist, I only need the server)
- **Does an MCP Server exist?:** ✅ Yes, community server

### 3. Internal API (internal microservices)
- **Service:** The work's internal API (not public)
- **AI Hosts:** Claude Code, Cursor
- **M×N:** 2 × 1 = 2 custom integrations
- **M+N:** 2 + 1 = 3 (I only need to build the server)
- **Does an MCP Server exist?:** ❌ No, I'd have to build it myself

## Totals
- **Total M×N:** 3 + 3 + 2 = 8 custom integrations
- **Total M+N:** In reality, I only need to build 1-3 MCP servers
  (the clients already exist in the hosts)
- **Savings:** >60% of development effort

## Reflection
- **Most valuable integration:** The Internal API, because it's the only
  one that doesn't have an existing MCP Server and would be the most impactful for
  my team. It could be my final project in module 8.

Troubleshooting

"Claude Code doesn't use the MCP Server's tools"

Cause: Claude Code decides when to use tools based on your request. If your question doesn't require file access, it won't use the Filesystem server.

Solution: Make specific requests that require file access:

• ✅ "Read my project's package.json file"
• ✅ "List the files in my directory"
• ❌ "What is MCP?" (this doesn't require the filesystem)

"Error: ENOENT — no such file or directory"

Cause: The directory you configured doesn't exist or the path has a typo.

Solution:

# Verify that the directory exists
ls -la /your/configured/directory

# If you need to change the directory:
claude mcp remove filesystem
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /correct/directory

"Error: permission denied"

Cause: The MCP Server doesn't have permissions to access the directory.

Solution:

# Verify permissions
ls -la /your/directory

# Adjust if needed
chmod 755 /your/directory

"npx takes a long time to start"

Cause: npx downloads the package every time it runs if it's not cached.

Solution:

# Install globally for a faster startup
npm install -g @modelcontextprotocol/server-filesystem

# Reconfigure using the global path
claude mcp remove filesystem
claude mcp add filesystem -s user -- server-filesystem /your/directory

"The server appears as disconnected"

Cause: The server couldn't start. It could be a Node.js problem, a package problem, or a configuration one.

Solution:

# 1. Verify that npx can run the server manually
npx -y @modelcontextprotocol/server-filesystem --help

# 2. If it fails, it may be a Node.js version problem
node --version
# You need v18+

# 3. Clean the npm cache and retry
npm cache clean --force
claude mcp remove filesystem
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /your/directory

# 4. Restart Claude Code (new session)
claude

"The tools don't appear in /mcp"

Cause: The server was registered but didn't connect correctly when the session started.

Solution:

# 1. Verify the configuration
claude mcp list

# 2. If it appears listed but not connected, try:
# - Close Claude Code completely
# - Reopen with: claude

# 3. If it persists, remove and re-add:
claude mcp remove filesystem
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /your/directory

# 4. If nothing works, verify there are no conflicts in settings.json
cat ~/.claude/settings.json

Summary

In this capsule:

• You prepared your environment: Node.js, npm, npx, and a test directory
• You configured your first MCP Server (Filesystem) in Claude Code
• You verified the connection with the /mcp command and confirmed that the tools are available
• You used the server to read files, list directories, search files, and create files
• You observed the MCP flow in action: Host → Client → Server → Response
• You noticed key patterns: automatic discovery, intelligent tool selection, write confirmation
• You experimented (optionally) with multiple simultaneous servers (Filesystem + Memory)
• You completed practice exercises with real MCP tools
• You completed the mini-project: mapping M×N vs M+N integrations

What you achieved: You went from "MCP is a concept" to "MCP is something that works in my terminal." This first hands-on contact is the foundation for everything that follows. Now when you read about MCP architecture (module 2) or primitives (module 3), you'll have an experiential anchor that makes everything more concrete.

What's next: Module 2

In Module 2 (Host-Client-Server Architecture) you're going to go deeper into how MCP works internally:

• The 3 layers of the architecture and how they interact
• The complete lifecycle of an MCP connection (from the handshake to the close)
• How data flows end-to-end (message format, serialization)
• How Claude Code handles multiple MCP servers simultaneously
• The JSON-RPC format the protocol uses under the hood
• Transports: stdio vs HTTP/SSE and when to use each one

You'll go from "I know it works" to "I understand how it works" — the knowledge you need to build your own MCP servers starting in module 3.

Additional resources

1. Claude Code MCP Configuration - Official documentation of MCP in Claude Code
2. Filesystem MCP Server - Source code of the server you used
3. Memory MCP Server - Second server you configured (optional)
4. Fetch MCP Server - Third server (exercise 1)
5. MCP Server Configuration Guide - Official configuration guide
6. MCP Debugging Tips - For advanced troubleshooting
7. MCP Inspector - Visual debugging tool (you'll use it in module 7)