Skip to content
BSWEN
Blog

How to Set Up Claude Code MCP Servers for Extended AI Capabilities

Cowrie
Cowrie
Dev @ Bswen

I was trying to get Claude Code to read files from my project directory, but it kept telling me it couldn’t access local files. The AI assistant could see my code through the chat interface, but I wanted it to actually interact with my filesystem, browsers, and databases. That’s when I discovered MCP servers.

What’s an MCP Server Anyway?

MCP (Model Context Protocol) servers are local processes that give Claude Code real tool capabilities. Unlike Skills which run inside the model, MCP servers run as separate processes on your machine. They can read files, control browsers, query databases, and connect to external APIs.

I spent hours confused about the difference between Skills and MCPs. Here’s the key distinction:

  • Skills: Run inside Claude’s model, defined as markdown files with prompts
  • MCP Servers: Run as local processes, provide actual tool implementations

My First MCP Configuration Attempt

I created my first mcp.json file and restarted Claude Code:

~/.claude/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/"]
    }
  }
}

Big mistake. I had just given Claude access to my entire filesystem - including system directories with sensitive files. The MCP server worked, but I had created a security risk.

The Correct Filesystem Setup

I fixed it by restricting access to my project directories only:

~/.claude/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/zhaocaiwen/projects"
      ]
    }
  }
}

After restarting Claude Code, I saw new tools appear in the UI. The filesystem MCP provided tools like read_file, write_file, list_directory, and search_files.

Configuration File Location

The configuration file location depends on your OS:

  • Mac/Linux: ~/.claude/mcp.json
  • Windows: C:\Users\username\.claude\mcp.json

I originally put the file in my project directory and wondered why nothing worked. The file MUST be in your home directory under .claude.

Adding More MCP Servers

Once I understood the pattern, I added more servers. Here’s my current setup:

~/.claude/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/zhaocaiwen/projects"
      ]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-fetch"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    }
  }
}

Each MCP server has three fields:

  • command: The executable to run (usually npx or python)
  • args: Arguments passed to the command
  • env: Optional environment variables (for API keys)

The JSON Syntax Trap

I wasted 30 minutes debugging why my configuration wouldn’t load. The issue? A missing comma:

Invalid JSON - Missing comma
{
  "mcpServers": {
    "filesystem": {
      "command": "npx"
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]  // Missing comma!
    }
  }
}

JSON is strict. Missing commas, unclosed brackets, trailing commas - all will silently fail. I now use a JSON validator before restarting Claude Code.

Environment Variables for API Keys

Some MCP servers need API keys. Don’t hardcode them in the config:

Wrong - Hardcoded API key
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "bsa123456789..."  // Never do this!
      }
    }
  }
}

Instead, reference environment variables that you set in your shell:

Right - Using environment variables
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

Then set the key in your shell profile:

~/.zshrc
export BRAVE_API_KEY="bsa123456789..."

MCP Servers That Don’t Need API Keys

I found that 6 out of 8 recommended MCP servers work without any API keys:

  1. filesystem - Read/write local files
  2. playwright - Browser automation
  3. fetch - HTTP requests
  4. memory - Persistent memory across sessions
  5. sequential-thinking - Structured reasoning
  6. git - Git operations

The ones requiring API keys:

  1. brave-search - Needs Brave Search API key
  2. context7 - Needs Context7 API key (optional for some features)

Verifying MCP Installation

After adding MCP servers, I check they loaded correctly:

  1. Restart Claude Code completely (not just the session)
  2. Look for tools in the UI - they appear as available functions
  3. Try using one: “Read the file /Users/me/projects/test.txt”

If tools don’t appear, check:

  • JSON syntax is valid
  • File is in ~/.claude/mcp.json
  • Dependencies are installed (npx handles this automatically for most)
  • Restart Claude Code after any config change

Common Installation Issues

Issue: “npx not found”

The npx command comes with Node.js. Install it first:

Terminal
# Check if installed
npx --version


# If not, install Node.js (includes npx)
brew install node  # Mac
# or download from nodejs.org

Issue: MCP server won’t start

Some MCP servers need Python:

Python-based MCP server
{
  "mcpServers": {
    "my-python-mcp": {
      "command": "python",
      "args": ["-m", "my_mcp_server"]
    }
  }
}

Make sure Python and required packages are installed:

Terminal
python --version
pip install my_mcp_server

Issue: Tools appear but don’t work

Check the MCP server logs. On Mac:

Terminal
# Claude Code logs
tail -f ~/.claude/logs/mcp.log

The logs show connection errors, missing dependencies, and configuration problems.

Security Best Practices

After my initial security scare, I follow these rules:

  1. Never open root directory - Limit filesystem MCP to specific project folders
  2. Use environment variables - Never commit API keys in mcp.json
  3. Review tool permissions - Understand what each MCP can access
  4. Audit regularly - Remove unused MCP servers

The filesystem MCP is particularly powerful. It can read, write, and delete files within its allowed directories. Grant access only where necessary.

Debugging MCP Connections

When an MCP server fails to connect, I check:

  1. JSON syntax - Use a linter or online validator
  2. Command availability - Run npx -y @modelcontextprotocol/server-filesystem --help manually
  3. Logs - Check ~/.claude/logs/ for error messages
  4. Environment - Ensure API keys are set in the shell
Testing MCP server manually
# Test if the server can start
npx -y @modelcontextprotocol/server-filesystem /Users/me/projects


# If this works, the config should work too

The Restart Requirement

Claude Code only reads mcp.json at startup. After any configuration change:

  1. Close Claude Code completely
  2. Wait a few seconds
  3. Open Claude Code again
  4. Check if tools appear

I initially tried refreshing the session, but that doesn’t reload the MCP configuration. Full restart is required.

Combining Multiple MCPs

The real power comes from combining MCPs. I can now:

  • Read documentation with fetch MCP
  • Search code with filesystem MCP
  • Test in browser with playwright MCP
  • Save context with memory MCP

Each MCP provides specialized tools that work together in a single Claude Code session.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: