How to Add an MCP Server to Claude Desktop (2026)

Adding an MCP server to Claude Desktop takes under 2 minutes. You open the config file, paste the server's JSON block, save the file, and restart Claude Desktop. This guide walks through every step with exact file paths, example configs for both hosted and local servers, and the verification process. Works on macOS, Windows, and Linux.

Before you start

Claude Desktop installed. Download from claude.ai/download if needed.

An API key for the server you want to add. For Hooklayer (the QA gate and slop filter for AI-generated content), sign up free at hooklayer.dev/auth/signup.

A text editor (VS Code, Notepad, TextEdit, nano, or any code editor).

Step 1: Open the config file

Claude Desktop stores its MCP server configuration in a single JSON file. The path depends on your operating system.

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Open Terminal and run: open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Open Run (Win+R), paste the path above, and press Enter.

Linux

~/.config/Claude/claude_desktop_config.json

If the file does not exist, open Claude Desktop once (it creates the file on first launch), then close it.

Full config file reference

Step 2: Add the server block

The config file has one top-level object with an mcpServers key. Each server gets its own entry. Here are examples for both transport types.

Hosted server (streamable-http)

Use this for SaaS MCP servers like Hooklayer. Nothing to install locally.

Add Hooklayer (hosted)

{
  "mcpServers": {
    "hooklayer": {
      "type": "streamable-http",
      "url": "https://hooklayer.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer hl_live_YOUR_KEY_HERE"
      }
    }
  }
}

Local server (stdio)

Use this for open-source servers or self-hosted tools. Requires the package installed locally.

Add a local MCP server (stdio)

{
  "mcpServers": {
    "my-local-server": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Adding multiple servers

Put each server as a separate key in the mcpServers object. They all load when Claude starts.

Multiple servers in one config

{
  "mcpServers": {
    "hooklayer": {
      "type": "streamable-http",
      "url": "https://hooklayer.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer hl_live_YOUR_KEY"
      }
    },
    "another-server": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@example/other-server"]
    }
  }
}

Step 3: Save and restart Claude Desktop

Save the config file. Then fully quit Claude Desktop (not just close the window) and reopen it.

macOS

Right-click the dock icon and select Quit. Then reopen from Applications.

Windows

Right-click the system tray icon and choose Exit. Then reopen from Start menu.

Linux

Close the window and kill any background process. Then relaunch.

Step 4: Verify the connection

Look for the hammer icon

After restarting, check the bottom-left of the chat input area. A hammer icon appears when MCP servers are connected. If it is missing, your config has an error.

Click the hammer

It lists every connected server and the number of available tools. For Hooklayer, you should see 8 tools: analyze_account, score_hook, viral_remix, trend_pulse, find_viral_template, match_voice, predict_virality, and search_videos.

Test with a prompt

Try: "Score this hook: Stop scrolling if you have oily skin." Claude should call score_hook and return a score between 0 and 100 with feedback.

Troubleshooting

Hammer icon not showing

Validate your JSON at jsonlint.com. Common errors: trailing comma, missing closing brace, unescaped backslash in Windows paths. Also confirm you fully quit and restarted (not just closed the window).

Server shows but tools fail

Check your API key. For Hooklayer, verify the key starts with hl_live_ and is pasted correctly (no trailing whitespace). For stdio servers, verify the command path is absolute.

Stdio server not found

Claude Desktop runs with a minimal PATH. Use the full path to the command (e.g., /usr/local/bin/npx instead of just npx). Run which npx (macOS/Linux) or where npx (Windows) to find the full path.

Frequently asked questions

How long does it take to add an MCP server to Claude Desktop?

Under 2 minutes for hosted servers (streamable-http). You open the config file, paste the server block, save, and restart Claude Desktop. Local stdio servers take slightly longer because you may need to install npm packages first.

Where is the Claude Desktop config file?

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json. Linux: ~/.config/Claude/claude_desktop_config.json. Claude Desktop creates this file on first launch.

What is the difference between adding a hosted server and a local server?

A hosted server (streamable-http) needs a URL and optional headers in the config. Nothing is installed locally. A local server (stdio) needs a command and args. The client starts the process locally. Hosted servers are simpler for non-developers.

Can I add multiple MCP servers at once?

Yes. Add each server as a separate key inside the mcpServers object. All servers load in parallel when Claude Desktop starts. You can mix hosted and local servers in the same config file.

Why do I not see the hammer icon after adding a server?

Three common causes: (1) JSON syntax error in the config file, even a trailing comma breaks it. Validate at jsonlint.com. (2) You did not fully restart Claude Desktop. Quit the app completely (not just close the window), then reopen. (3) The server URL or command is incorrect.

Do I need an API key for every MCP server?

Most commercial servers require an API key for authentication. Some open-source servers work without one. Hooklayer requires a free hl_live_ key (50 credits, no card). The key goes in the Authorization header for hosted servers or in the env object for local servers.