MCP Practice: Challenges in Claude Desktop Setup (Node.js and JSON Barriers)

Introduction

Hello. So far, as a reading log for 'Gentle Introduction to MCP,' I have been learning about the safety of AI agents (roots) and development efficiency (inspectors).

After learning the theory, I finally tried to set up an MCP server on Claude Desktop to experience "tool usage," which is the real thrill of MCP. However, the result was that the MCP server setup alone did not work out, and I ran out of time.

In this article, I will share why the MCP server setup, which seemed like something anyone could easily do, got stuck. I'll cover the technical hurdles and the troubleshooting experience I gained.

---

1. Setup Journey and a Smooth Start

This time, I challenged myself to start an MCP server that operates the file system using Claude Desktop. This is the first step toward the experience of letting AI create or delete files and folders just by giving instructions in natural language.

Steps that went smoothly

1. Installing Claude Desktop: Installing the application and creating an account were completed smoothly.
2. Installing Node.js: The installation of Node.js, which is necessary for running the MCP server, was also completed successfully.

Theory of Server Setup

The core of the setup is to open the JSON file from the Claude Desktop settings and write the startup information for the MCP server.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        // ... MCP server package name and allowed access paths ...
        "C:\\\\Users\\\\Username\\\\Desktop"
      ]
    }
  }
}

Theoretically, by saving this configuration and restarting Claude Desktop, the available tools should have been recognized and the setup completed.

---

2. The Wall of "JSON Configuration"

However, in reality, even after correctly editing the JSON file and restarting multiple times, the filesystem server was not recognized from the "Search & Tools" button in Claude Desktop.

Technical Issues Experienced

To investigate the cause of this problem, I debugged the Node.js environment on the terminal.

1. Fixing Environment Errors: In the first attempt, I faced an issue where the npx command did not work due to an npm cache corruption error (ECOMPROMISED).
   • Executing npm cache clean --force in the terminal resolved this environment error.
2. Identifying the Execution Environment: After fixing the error, I tested whether the MCP server could be started from the terminal and confirmed the following:
   • Node.js and the MCP server package itself are working normally.
   • The problem is likely in the process where Claude Desktop loads the JSON configuration and attempts to start the server in the Windows environment.

The Ultimate Challenge: OS and JSON Path Issues

The final cause is presumed to be a mismatch between the Windows path in the JSON (C:\\Users\\username\\Desktop) and the path format required internally by Claude Desktop (such as slash separators or the presence/absence of a drive letter).

Even though the JSON syntax itself was correct, the "wall of path interpretation" between the OS environment and the application prevented the setup from being completed.

---

3. Summary: Experiences of Failure Deepen Knowledge

Although I gave up on the setup this time due to running out of time, this experience was very valuable.

• Knowledge that can only be gained through practice: I gained a deep understanding of how to debug the Node.js environment, the strict requirements for path descriptions in JSON, and the role of the npx command—things I wouldn't have known just by reading a book.
• Confidence in how MCP works: I was able to manually confirm the mechanism where the MCP server runs as an external Node.js process and defines its startup configuration via JSON.

Next time, based on the knowledge and troubleshooting results I've gained, I definitely want to succeed in starting the MCP server.

References

'Gentle Introduction to MCP' (written by Minoru Mita and Yu Otsubo)
https://www.shuwasystem.co.jp/book/9784798075730.html

MCP Official Documentation: Connect to local servers
https://modelcontextprotocol.io/docs/develop/connect-local-servers