What causes "MCP server args must be an array" in Mintplex-Labs/anything-llm?

Make args an array of separate strings, one element per argument

MCP server args must be an array

Error message

MCP server args must be an array

What it means

For stdio-type MCP servers (entries with a "command" property), the hypervisor validates that "args", when present, is an array. It uses hasOwnProperty so a missing args is fine, but any non-array value (string, object, null as a present key) throws this error during boot validation.

Solutions

Make args an array of separate strings, one element per argument
Keep flags and their values as distinct array elements
Validate the JSON shape before saving (args is optional, but if present must be an array)
Re-boot MCP servers after fixing the JSON

Example fix

// before
{ "my-server": { "command": "npx", "args": "-y @modelcontextprotocol/server-memory" } }

// after
{ "my-server": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] } }

Defensive patterns

Strategy: validation

Validate before calling

function validateStdioArgs(server) {
  if ('args' in server && !Array.isArray(server.args))
    throw new Error('stdio server "args" must be an array of strings');
}

Type guard

function hasValidArgs(server) {
  return !('args' in server) || (Array.isArray(server.args) && server.args.every((a) => typeof a === 'string'));
}

Try / catch

try {
  await hypervisor.bootMCPServers();
} catch (err) {
  if (err.message === 'MCP server args must be an array') {
    // convert a string arg to [string] or prompt the user to fix the JSON
  }
  throw err;
}

Prevention

Build args as arrays in any UI that creates stdio entries — never accept a single string
JSON-schema-validate entries (args: array of strings, optional) before saving
Split shell-style strings with a shell-quote parser rather than storing them raw

When it happens

Trigger: mcp_servers.json stdio entry with "args": "--port 3000" (a single string), "args": { "0": "--port" }, or "args": null where the key exists.

Common situations: Hand-writing the JSON and quoting the whole argument list as one string; shell-style habits (args: "-y @modelcontextprotocol/server-everything"); tools that emit objects instead of arrays.

Related errors

AI-assisted analysis of Mintplex-Labs/anything-llm@3aec848f28 (2026-08-18). Data as JSON: /api/errors/4b1cc332b1d576a1. Report an issue: GitHub.

Appendix: source

Thrown at server/utils/MCP/hypervisor/index.js:394

        throw new Error(
          `MCP server "${name}": missing required "url" for ${server.type || "sse"} transport`
        );
      }

      try {
        new URL(server.url);
      } catch {
        throw new Error(`MCP server "${name}": invalid URL "${server.url}"`);
      }
      return;
    }

    if (type === "stdio") {
      if (
        Object.prototype.hasOwnProperty.call(server, "args") &&
        !Array.isArray(server.args)
      )
        throw new Error("MCP server args must be an array");
    }
    return;
  }

  /**
   * Setup the server transport by type and server definition
   * @param {Object} server - The server definition
   * @param {MCPServerTypes} type - The server type
   * @returns {Promise<StdioClientTransport | StreamableHTTPClientTransport | SSEClientTransport>} - The server transport
   */
  async #setupServerTransport(server, type) {
    // if not stdio then it is http or sse
    if (type !== "stdio") return this.createHttpTransport(server);

    return new StdioClientTransport({
      command: server.command,
      args: server?.args ?? [],
      ...(await this.#buildMCPServerENV(server)),

View on GitHub (pinned to 3aec848f28)