Originally published at claudeguide.io/claude-code-mcp-server-setup

Claude Code MCP Server Setup: A Practical Guide (2026)

MCP (Model Context Protocol) lets Claude Code talk to external tools and data sources through a standardized interface. Instead of Claude having to search the web or read files manually, an MCP server can expose tools that Claude calls directly — fetching Slack threads, querying databases, running browser automation, or reading from any API in 2026.

This guide covers the practical setup: where the config lives, how to add servers, the differences between local and remote servers, and how to debug when tools don't appear.

Where the MCP config lives

Claude Code reads MCP server configuration from two places:

User-level (applies to all projects):

~/.claude/claude_desktop_config.json

Project-level (checked into your repo):

.claude/mcp.json    # or claude_desktop_config.json

Project-level takes precedence for the servers defined there. Both files are merged — you can have global servers (GitHub, Slack) and project-specific servers (a database connection, a local test runner) active simultaneously. Both MCP config files and hook definitions live inside the same .claude/ directory — see the Claude Code settings.json reference for the full schema.

Config format

Both files use the same JSON structure:

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

The key fields:

• "type": "stdio" for local processes, "sse" for remote HTTP servers
• "command": the executable to run
• "args": arguments passed to the command
• "env": environment variables injected into the server process

Adding a local stdio server

Most community MCP servers are npm packages that run as local processes. The pattern:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

After editing the config, restart Claude Code. New servers take effect on next launch.

Adding a remote SSE server

For servers that run as HTTP endpoints (e.g., a deployed MCP server your team runs):

{
  "mcpServers": {
    "company-data": {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

SSE servers don't require a local process. Claude Code connects to the URL and maintains a server-sent events connection for the duration of the session.

Verifying servers loaded correctly

In a Claude Code session, run:

/mcp

This shows all configured MCP servers, their connection status, and the tools they expose. A healthy output looks like:

MCP Servers:
  ✓ filesystem — connected (3 tools: read_file, write_file, list_directory)
  ✓ github — connected (8 tools: get_file_contents, create_issue, ...)
  ✗ postgres — failed to connect (exit code 1)

If a server shows failed to connect, that's the signal to debug.

Debugging a server that won't connect

Step 1: Run the server command manually.

Take the exact command from your config and run it in your terminal:

npx -y @modelcontextprotocol/server-postgres "postgresql://localhost/mydb"

If it exits immediately with an error, you'll see the real error message. Common causes:

• The npm package name is wrong or misspelled
• The connection string is malformed
• Required environment variables aren't set in your shell

Step 2: Check environment variable injection.

Env vars in the MCP config are injected into the server process, but they aren't available in your shell. If the server needs GITHUB_PERSONAL_ACCESS_TOKEN, it must be in the config's "env" block, not just in your .zshrc:

"env": {
  "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_actual_token"
}

Step 3: Check MCP logs.

Claude Code writes server stderr to logs. On macOS:

# For Claude Desktop app
cat ~/Library/Logs/Claude/mcp-server-{server-name}.log

# For Claude Code CLI
cat ~/.claude/logs/mcp-{server-name}.log

The logs show the exact error the server process emitted before exiting.

Step 4: Verify the server version is compatible.

MCP is a living protocol. Some community servers target an older SDK version and haven't been updated. Check the package's GitHub issues for "Claude Code compatibility" before spending time debugging an incompatibility.

Writing your own MCP server

If you need to expose internal data or tools that don't have a community server, the SDK makes this straightforward:

typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "my-internal-tools", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () =

40 slash command templates. Token-optimized variants. JSONL file for direct import. Tested in production sessions.

[→ Get Claude Code Power Prompts 300 — $29](https://shoutfirst.gumroad.com/l/agfda?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-code-mcp-server-setup)

*30-day money-back guarantee. Instant download.*