Writing /MCP servers /2026-07-19

Setting Up MCP Servers with Claude Desktop and Claude Code

A practical walkthrough for configuring MCP servers in Claude Desktop and Claude Code: where the config lives, what the JSON looks like, and how to debug when things don't connect.

Part of the MCP reading path. Start here →

Written by
Read time
9 minutes
Updated
2026-10-01
Topic
MCP servers

Setting up MCP servers in Claude Desktop and Claude Code is straightforward once you know where the config lives and how the client discovers servers. But the docs scatter this information across multiple pages and don’t cover the debugging workflow when things refuse to connect. I’ve configured four servers (scry, tome, lore, and flume) and hit every common failure mode at least once. This is the setup guide I wish existed when I started.

If you’re not familiar with what MCP servers are or why you’d want them, start with my complete guide to the Model Context Protocol. This post assumes you already have a server binary or know which server you want to run, and you just need to wire it up to your client.

Claude Desktop setup

Claude Desktop reads its MCP configuration from a JSON file on disk. The location depends on your OS:

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

Use Settings > Developer > Edit Config to open the file. These paths cover the macOS and Windows desktop apps; check the documentation for any third-party Linux client separately.

If the file doesn’t exist, create it. The structure is a top-level object with an mcpServers key. Each entry under that key is a server name mapped to its configuration.

Here’s what a real config looks like with multiple servers:

{
  "mcpServers": {
    "scry": {
      "command": "/usr/local/bin/scry",
      "args": ["serve"],
      "env": {
        "SCRY_INDEX_PATH": "/Users/jeff/.scry/index"
      }
    },
    "tome": {
      "command": "/usr/local/bin/tome",
      "args": ["serve", "--dsn", "postgres://localhost:5432/myapp"]
    },
    "lore": {
      "command": "/usr/local/bin/lore",
      "args": ["serve", "--repo", "/Users/jeff/workspace/myproject"]
    }
  }
}

Each of those is a stdio server. Claude Desktop spawns the process and communicates over stdin/stdout. This is the default and what you’ll use for any locally-installed server binary.

For a remote MCP server, use Settings > Connectors > Add custom connector and enter its server URL. A remote URL in claude_desktop_config.json is not the same setup as a local stdio server. Remote connectors connect from Claude’s cloud infrastructure, so localhost on your laptop is not reachable through that route. See the remote connector guide for current requirements.

After saving the config, restart Claude Desktop completely. It only reads the config file at startup.

Claude Code setup

Claude Code takes a different approach. Instead of editing JSON by hand, you use the CLI:

claude mcp add scry -- /usr/local/bin/scry serve
claude mcp add tome -- /usr/local/bin/tome serve --dsn postgres://localhost:5432/myapp
claude mcp add lore -- /usr/local/bin/lore serve --repo /Users/jeff/workspace/myproject

The format is claude mcp add <name> -- <command> [args...]. Everything after -- is the command and arguments that will be spawned as a stdio server.

For HTTP servers:

claude mcp add --transport http remote-server http://localhost:8080/mcp

You can list configured servers with claude mcp list and remove them with claude mcp remove <name>.

The default scope is local: the server is private to you and available only in the project where you added it. The CLI stores that definition under the project’s entry in ~/.claude.json.

For a shared project definition, add --scope project:

claude mcp add --scope project --transport stdio scry -- /usr/local/bin/scry serve

This writes the server definition to .mcp.json at the project root:

{
  "mcpServers": {
    "scry": {
      "type": "stdio",
      "command": "/usr/local/bin/scry",
      "args": ["serve"]
    }
  }
}

Use --scope user when you want the server available across your projects. User-scoped definitions also live in ~/.claude.json, outside any one project’s entry. Project servers require approval before Claude Code uses them.

Server definitions and tool permissions are separate. .mcp.json declares what to connect to; .claude/settings.json controls project settings such as permission rules. Start with the normal tool approval prompts and add only the permissions your workflow needs. The Claude Code MCP documentation covers scope precedence and configuration options.

Verifying the connection

Once configured, you need to confirm your servers actually connected.

In Claude Desktop: Check the server in Settings > Developer and the tools available in your conversation. If a local server fails, inspect its MCP logs; on macOS these are under ~/Library/Logs/Claude. The local server guide includes troubleshooting steps for both supported desktop platforms.

In Claude Code: Run claude mcp list. Check the reported connection status. Inside a session, /mcp lets you inspect connected servers and handle authentication. A saved configuration alone does not prove the server can start or finish its handshake.

If tools aren’t appearing, the issue is almost always in the initialization handshake. The server starts, the client sends initialize, and if the server doesn’t respond correctly, the client gives up. Check that your server binary actually runs when invoked with the configured arguments. Try running the exact command from your terminal first.

Debugging common issues

These are the failures I’ve hit repeatedly, in order of how often they occur.

Server binary not found

The most common issue. Claude Desktop and Claude Code spawn the server process using the command field, and that command needs to resolve. If you installed a server to ~/go/bin/scry but your config says "command": "scry", it won’t work unless ~/go/bin is in the PATH that Claude sees.

The fix: always use absolute paths in your config. Not "command": "scry" but "command": "/Users/jeff/go/bin/scry". Don’t rely on shell PATH expansion because the client may not source your shell profile.

Server crashes on startup

The server binary exists but immediately exits. This usually means it’s missing a required flag, can’t find a config file, or can’t connect to a dependency (like a database for tome).

Debug it by running the exact command from your terminal:

/usr/local/bin/tome serve --dsn postgres://localhost:5432/myapp

If it prints an error and exits, you’ve found your problem. MCP servers in stdio mode should start and then block waiting for input on stdin. If they exit, the client sees a broken pipe and gives up.

Tools not appearing after connection

The server connects but reports zero tools. This usually means the server’s tools/list handler is returning an empty list. Some servers require initialization steps (scry needs an index built first, tome needs database access) and expose no tools until that prerequisite is met.

Check your server’s documentation for required setup steps. For my servers, scry index must run before scry serve has anything to offer.

Transport mismatch

You configured a stdio server with a url field, or an HTTP server with command and args. The client tries the wrong transport, gets garbage back, and disconnects. In Claude Code, stdio entries use command/args; HTTP entries use type: "http" and url. In Claude Desktop, keep local stdio configuration separate from remote connectors.

Environment variables

Some servers need environment variables that exist in your shell but not in the process Claude spawns. Use the env field in your config to explicitly pass them:

{
  "command": "/usr/local/bin/scry",
  "args": ["serve"],
  "env": {
    "SCRY_INDEX_PATH": "/Users/jeff/.scry/index",
    "HOME": "/Users/jeff"
  }
}

My setup

Here’s what my Claude Code configuration looks like. I run four MCP servers that form a context layer around my development environment:

  • scry: code intelligence. Symbol definitions, references, call graphs. Pre-indexed with SCIP into BadgerDB.
  • tome: database schema. Table descriptions, column types, foreign key relationships. Connects to my local Postgres.
  • lore: git intelligence. Blame, commit history, co-change patterns, contributor analysis.
  • flume: HTTP traffic inspection. Captures requests between browser and dev server for debugging.

Here is a .mcp.json example for those four servers. Replace the paths and arguments with the ones for your installation:

{
  "mcpServers": {
    "scry": {
      "command": "/Users/jeff/go/bin/scry",
      "args": ["serve"],
      "env": {
        "SCRY_INDEX_PATH": "/Users/jeff/.scry/index"
      }
    },
    "tome": {
      "command": "/Users/jeff/go/bin/tome",
      "args": ["serve", "--dsn", "postgres://localhost:5432/myapp"]
    },
    "lore": {
      "command": "/Users/jeff/go/bin/lore",
      "args": ["serve"]
    },
    "flume": {
      "command": "/Users/jeff/go/bin/flume",
      "args": ["serve", "--port", "9090"]
    }
  }
}

The four servers work together. When I’m debugging a bug, Claude uses scry to find the relevant code, lore to check who changed it last and why, tome to verify the database schema matches what the code expects, and flume to inspect the actual HTTP traffic hitting the endpoint. Each server does one thing well, and the agent composes them as needed. I wrote about this architecture in depth in The Context Layer.

Tips

Restart behavior. Claude Desktop only reads MCP config at launch. You must fully restart it after config changes. Claude Code re-reads config each time you start a new session, so changes take effect on the next conversation.

Environment variables in Claude Code. Use --env or the env field in the server definition. Place another CLI option after the environment value so the variadic flag does not consume the server name. For example:

claude mcp add --env SCRY_INDEX_PATH=/Users/jeff/.scry/index --transport stdio scry -- /usr/local/bin/scry serve

Keep secrets out of shared project files. Replace this example path with your own.

Managing many servers. I’ve run up to six servers simultaneously without issues. Each stdio server is a separate process that Claude spawns and manages. The overhead is minimal for well-built servers. Mine use around 20MB of RAM each. But poorly-built servers that do expensive work at startup can slow down session initialization noticeably.

Performance with many tools. Tool loading depends on the client and its tool-search settings. Check the tools available in your session and measure the workflow you actually use instead of assuming every definition is sent on every request. Clear names and focused descriptions still help the agent choose the right tool.

Absolute paths everywhere. I cannot stress this enough. Relative paths, tilde expansion, and PATH lookups are all sources of subtle failures. Use absolute paths for the command, for any file arguments, and for environment variable values that reference the filesystem.

Test the command manually first. Before adding any server to your config, run the exact command in your terminal and verify it starts without errors and waits for input. Starting successfully rules out some failures; still check the client’s environment and the MCP handshake. If it doesn’t work standalone, no amount of config fiddling will fix it.


This post is part of my series on the Model Context Protocol. For the conceptual overview, read What Are MCP Servers?. For building your own, see Building MCP Servers in Go. For the architectural pattern behind my four servers, see The Context Layer.

Questions

How do I add an MCP server to Claude Desktop?

Edit the claude_desktop_config.json file (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) and add your server under the mcpServers key. For local stdio servers, provide a command and optional args and env. Add remote servers through Settings > Connectors instead. Restart Claude Desktop after saving.

How do I add an MCP server to Claude Code?

Run `claude mcp add <name> -- <command> <args>` from your terminal. For example: `claude mcp add scry -- scry serve`. The default local scope saves it privately for the current project. Use --scope project to write shared definitions to .mcp.json, or --scope user to make the server available across your projects.

Where is the Claude Desktop MCP config file?

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%/Claude/claude_desktop_config.json. Use Settings > Developer > Edit Config to open the file for your installation.

Why is my MCP server not connecting in Claude?

The most common causes are: the server binary isn't in PATH (use absolute paths in config), the server crashes on startup (check stderr output), or there's a transport mismatch (stdio server configured as HTTP or vice versa). In Claude Desktop, check the MCP status indicator. In Claude Code, run `claude mcp list` to see connection status.

Can I use project-specific MCP servers in Claude Code?

Yes. Use --scope project with claude mcp add to create a root .mcp.json file for shared server definitions. Claude Code asks you to approve project servers before using them. Keep permission settings separate in .claude/settings.json.

Start a project conversation

Email Jeff

Write your note here, then open it in your email app. This site sends nothing: your email app opens with this draft and you press send there. No email app? Copy the address or the draft instead.

Open in your email app ↗

To jeff@hooton.codes · Closing this window discards the draft.