Master the configuration file that connects Claude Desktop to MCP Servers.
The file claude_desktop_config.json is the connection point between Claude Desktop and the world of MCP Servers. It’s a simple JSON file that lists all the MCP servers Claude can access. Without it, Claude Desktop doesn’t know any external tools exist—it works only as a conventional chat.
O claude_desktop_config.json is a JSON-format configuration file that serves as the “catalog” of MCP Servers available to Claude Desktop. Each entry in this file describes a server: its name, the command to start it, and the required arguments. When Claude Desktop starts, it reads this file and tries to connect to each listed server. If the file doesn't exist or is empty, Claude won't have access to any MCP tools—it will work only as a chat assistant without external tools.
Think of config.json as the "contact list" of Claude Desktop. Just as your phone can only call numbers in your contacts, Claude Desktop can only use tools from servers listed in config.json. Adding a server to the file is like adding a new contact—from that moment on, Claude knows that the server exists and can connect to it.
The configuration file is in a specific directory for each operating system. It’s important to know exactly where it is, because you’ll edit this file frequently throughout the course. If the file or directory doesn’t exist yet, you’ll need to create it manually.
The file’s full path varies by operating system. Claude Desktop always looks for the file in the same location, and there’s no way to change that path. You need to put the file exactly in the expected directory so Claude can find it.
~/Library/Application Support/Claude/claude_desktop_config.json
Open in terminal: open ~/Library/Application\ Support/Claude/
%APPDATA%\Claude\claude_desktop_config.json
Open in Explorer: explorer %APPDATA%\Claude
~/.config/Claude/claude_desktop_config.json
Open in terminal: xdg-open ~/.config/Claude/
The file may not exist initially. If the Claude directory exists but the file doesn't, create it manually with the minimum content: {"mcpServers": {}}. If the directory doesn't exist either, create it too. On macOS, the Library folder is hidden by default—use Cmd+Shift+. in Finder to show hidden folders, or navigate via the terminal.
Understanding the configuration file structure is essential. It follows a well-defined JSON format with a simple, predictable hierarchy. Once you understand the pattern, adding new servers becomes a mechanical task that takes just a few seconds.
The file structure is a JSON object with a main field: "mcpServers". Within it, each server is represented as a key (the server name) pointing to an object with two required fields:
"python", "npx", "node")["-y", "@pacote/server"])Optionally, a server can have the field "env" for environment variables (such as API keys).
Here’s a complete, commented example of the format:
{
"mcpServers": {
"meu-server": {
"command": "npx",
"args": ["-y", "@pacote/mcp-server"]
},
"outro-server": {
"command": "python",
"args": ["-m", "meu_server"],
"env": {
"API_KEY": "sua-chave-aqui"
}
}
}
}
Each server is independent. You can have as many as you want, as long as each name is unique.
Now that you understand the file structure, let’s go through the practical process of registering a new MCP Server. Each server needs an identifying name, a command to run it, and the correct arguments. Following the process step by step ensures everything works on the first try.
Registering an MCP Server means adding a new entry to the object "mcpServers" from config.json. Each entry needs: a name (the object's key — should be descriptive and unique), a command (the executable: python, npx, node, uvx, etc.), and args (an array with the server’s path or package and its arguments). Claude Desktop will use this information to start the server automatically when needed.
Set a descriptive name for the server. Use kebab-case (e.g., meu-filesystem, github-tools). The name should clearly indicate what the server does.
Identify the correct executable: npx for npm packages, python or uvx for Python servers, node for direct JS scripts.
Build the argument array: for npx, include "-y" followed by the package name and any server arguments. For Python, use "-m" followed by the module.
Save the config.json file, completely close Claude Desktop, and reopen it. The new server should appear among the available tools (hammer icon).
Setting up the JSON file for the first time is simple, but a few subtle errors can prevent MCP Servers from loading. Knowing the most common issues and how to diagnose them saves hours of frustration. Most issues come down to malformed JSON or incorrect paths.
The most frequent config.json configuration errors are:
\\) or use forward slashes (/).command specified is not in the system PATH. npx or python cannot be found by Claude Desktop.Claude Desktop does not display clear error messages when config.json has issues. If the servers don’t appear after restarting, the first step is always to validate the JSON. Paste the file’s contents into jsonlint.com or use VS Code validation (which automatically underlines syntax errors). A single extra comma can invalidate the entire file.
After creating or editing config.json, it’s essential to validate that everything is working. Validation involves restarting Claude Desktop, checking that the servers appear in the interface, and confirming that the tools are available. It’s a simple process, but it needs to be done correctly.
Configuration validation follows a precise sequence: save the file config.json, close completely Claude Desktop (not just minimizing it — actually closing it, including from the system tray), reopen the app, and check the hammer icon (🔨) in the chat input area. If the icon appears, click it to see the list of available tools. If the servers are connected, you’ll see the tool names for each server. If the icon doesn’t appear, there’s a configuration issue to investigate.
Save config.json and completely close Claude Desktop. On Windows, check the system tray. On macOS, use Cmd+Q.
Open Claude Desktop again. Wait a few seconds for the servers to start. Look for the hammer icon (🔨) next to the input field.
Click the hammer icon to see the list of tools. Each server contributes its own tools. Check that all expected tools are listed.
If the icon doesn’t appear, check the Claude Desktop logs for error messages related to MCP server startup.
If everything works, the hammer icon will show a number next to it—indicating how many tools are available. Click it to see each tool with its name and description. This is definitive confirmation that MCP is working. In the next module, we'll do exactly that with a real example server.
Next Module: 2.6 — First Test: Example MCP Server