Click any words you think contain an error. Click again to unmark.
Mark at least one word to submit.
The bug is the `args` value. It is written as one long string: `"-y @modelcontextprotocol/server-filesystem /Users/alice/projects"`. It needs to be a JSON array instead.
Why does this matter? A Claude Desktop **MCP server** entry tells the host how to launch a local process. The `command` is the program (`npx`), and `args` is the list of arguments handed to it. The host passes that list straight into a process-spawn call, where each element becomes one slot in the argv array.
When you write `args` as a single string, the host hands the whole string to the process as one argument. The `npx` launcher then looks for a package literally named `-y @modelcontextprotocol/server-filesystem /Users/alice/projects`, which does not exist, so the server fails to start.
The fix is to split the string on spaces into separate array elements: `["-y", "@modelcontextprotocol/server-filesystem", "/Users/alice/projects"]`. Now each flag, package name, and path lands in its own argv slot, and the server launches correctly.
The error is the type of `args`. It is a single space-delimited string, but it must be a JSON array of strings.
A Claude Desktop server entry maps onto a process spawn. The `command` is the executable and `args` is the argv list handed to it. The host does not tokenize the string for you. It passes each array element as one separate argument.
With the buggy config, the entire string becomes a single argv entry. So `npx` receives one argument: the whole joined string. It treats that as a package name, fails to resolve it, and the server never starts. You then see a silent connection failure in the host.
The correct shape gives each token its own element:
```
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/alice/projects"]
```
The broader rule is simple. Anything that maps to argv must be an array, never a pre-joined string. This mirrors how `execvp` and Node's `child_process.spawn` take an argument vector. The same discipline applies to passing secrets. Put credentials in an `env` object, not baked into `args` where they leak into process listings.
Quick reference
TL;DR
The `args` value is a single space-delimited string. It must be a JSON array of separate strings, because the host hands it straight to the process spawn as argv.
Think of ordering at a deli counter. If you hand the clerk one sticky note that says 'turkey swiss no mayo on rye', they treat it as one weird sandwich name and look confused. If you list each item separately, turkey, then swiss, then no mayo, then rye, they handle each one correctly. A process launcher works the same way. Each command-line flag, package name, and folder path is a separate instruction. When you cram them into one string, the launcher treats the whole thing as a single mystery argument and the server never starts. Splitting them into an array gives the launcher one clean instruction at a time, exactly the way it expects.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.
A remote MCP server reached over Streamable HTTP rather than a local process There is no command or args to spawn; you configure a URL and auth, so the argv array question does not arise at all.
A host that wraps the launch in an explicit shell command field If the host documents a shell string field, word splitting happens there; the array rule only applies to the direct spawn style used here.
Passing structured runtime configuration like a long allowlist Many servers prefer an env variable or a config file over a sprawling args array, which keeps the launch line readable and auditable.
Quick scan · 2–4 min
Everything important, quickly.
3 min: name the type error, explain the spawn to argv mapping, show the corrected array, then mention the secrets in env and absolute-path adjacent traps.