Skip to content
BSWEN
Blog

How to Configure MCP Servers in Claude Code: Complete Setup Guide

Cowrie
Cowrie
Dev @ Bswen

Purpose

I want to use Claude Code to access my files, query databases, and call APIs. But by default, Claude Code can only generate code - it cannot actually read or write files, connect to databases, or make HTTP requests.

The solution is MCP (Model Context Protocol) servers. These servers act as bridges between Claude Code and external tools.

What is MCP?

MCP is Anthropic’s open-source communication standard that lets Claude Code connect to external tools and services. Think of it as a plugin system:

  • Filesystem server → Read and write files
  • GitHub server → Manage issues and pull requests
  • PostgreSQL server → Query databases
  • Puppeteer server → Control a browser

The Configuration

There are two ways to configure MCP servers:

Add MCP servers via CLI
# Add filesystem access (most useful)
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects


# Add GitHub integration (requires token)
claude mcp add github -s user -e GITHUB_TOKEN=your_token -- npx -y @modelcontextprotocol/server-github


# Add PostgreSQL database access
claude mcp add postgres -s user -e DATABASE_URL=postgresql://user:pass@localhost/db -- npx -y @modelcontextprotocol/server-postgres

The -s user flag means the server is available globally. Use -s project for project-specific servers.

Method 2: JSON File Editing

For advanced users, edit ~/.claude.json directly:

~/.claude.json
{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"],
      "env": {}
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

Scope Levels

MCP servers have three scope levels:

┌─────────────────────────────────────────────────────────┐
│  Local   → .claude/settings.json (current directory)   │
│  User    → ~/.claude.json (global, all projects)       │
│  Project → .mcp.json (shared with team)                │
└─────────────────────────────────────────────────────────┘
  • User scope (-s user): Personal tools, available everywhere
  • Project scope (-s project): Team-shared tools, committed to git
  • Local scope (no flag): Current directory only

Management Commands

MCP management commands
# View installed servers
claude mcp list


# Test a server connection
claude mcp test filesystem


# Remove a server
claude mcp remove filesystem


# Enable debug mode
claude --mcp-debug


# Check MCP status in session
/mcp

Common Errors

Error 1: Invalid Server Name

Error message
tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}$'

The server name can only contain letters, numbers, underscores, and hyphens. No spaces or special characters.

Fix: Use valid names
# BAD
claude mcp add my-server! -- ...


# GOOD
claude mcp add my_server -- ...

Error 2: Windows Path Issues

On Windows, use forward slashes or double backslashes:

Fix: Use forward slashes on Windows
# BAD
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\name\Documents


# GOOD
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/name/Documents

Summary

In this post, I showed how to configure MCP servers in Claude Code. The key points are:

  1. Use claude mcp add command with -s user for global servers
  2. Start with filesystem server, then add GitHub and database servers
  3. Use -e flag for environment variables like tokens
  4. Avoid special characters in server names

MCP servers transform Claude Code from a coding assistant into a powerful automation tool.

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: