Connecting to Claude Desktop

Claude Desktop is the most polished MCP client and where most user-facing servers get their first real workout. This lesson gets your server from the Inspector into a proper Claude Desktop session.

Prerequisites

• Claude Desktop installed (from claude.ai/download)
• Your server from Module 2 working in the Inspector
• Comfort editing JSON config files

Step 1: Locate the Config File

The Claude Desktop config file lives at:

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

If the file does not exist, create it. It should look like this:

{
  "mcpServers": {}
}

Step 2: Add Your Server

Add an entry for your server. Assuming your server lives at /Users/you/hardcoded-mcp-server/server.py:

{
  "mcpServers": {
    "hardcoded-example": {
      "command": "/Users/you/hardcoded-mcp-server/.venv/bin/python",
      "args": ["/Users/you/hardcoded-mcp-server/server.py"]
    }
  }
}

Three things to notice:

• The key ("hardcoded-example") is a label Claude uses. Make it short.
• command is the full path to the Python interpreter in your project's venv. Full path matters; Claude Desktop does not know about your shell's PATH.
• args is the arguments to pass. First arg is your server file.

On Windows the command path uses backslashes: "C:\\Users\\you\\hardcoded-mcp-server\\.venv\\Scripts\\python.exe".

Step 3: Restart Claude Desktop

Fully quit and relaunch (not just close the window). The app reads the config file at startup only.

Step 4: Verify

Look for the small hammer icon in the message compose area. Click it. You should see your server listed with its tools. If the hammer icon is missing or your server is not there, the config is wrong or the server is failing to start.

Common Failures

"Server disconnected" in the tools list. Your server crashed on startup. Run it manually (python server.py) to see the error. Common cause: missing dependencies not installed in the venv that Claude is using.

Tools show up but calling any one returns "server error". Your tool implementation is raising an unhandled exception. Add error handling to return strings instead.

Nothing appears at all. Config file has JSON syntax errors, or the path to Python is wrong. Check both.

Environment Variables

If your server needs environment variables (API keys, DB URLs), add them to the config:

{
  "mcpServers": {
    "hardcoded-example": {
      "command": "/path/to/python",
      "args": ["/path/to/server.py"],
      "env": {
        "DATABASE_URL": "postgres://...",
        "API_KEY": "..."
      }
    }
  }
}

Do not put secrets in the config file if the file itself is not private. On a shared machine, prefer environment variables set at the OS level.

Iteration Loop

Once your server is wired up:

1. Ask Claude a question that should trigger your tool
2. Watch Claude decide whether to use it
3. If it does not, your tool description probably needs work
4. Edit the server file, restart Claude Desktop, try again

Restarting Claude Desktop every iteration is annoying but unavoidable with stdio-based servers. If you find yourself iterating a lot, use the Inspector for the tool-design pass and only test in Claude Desktop for the "does the model actually reach for this tool" pass.

Key Takeaway

Claude Desktop is the primary distribution channel for MCP servers. Wiring your server in is a small JSON edit plus a full app restart. Once connected, iterate quickly by refining tool descriptions between restarts. If you plan to publish a server, Claude Desktop is where you validate the user experience.