Mintplex-Labs/anything-llm · error · Error

MCP server args must be an array

Error message

MCP server args must be an array

What it means

Thrown by #validateServerDefinitionByType when a server is classified as stdio (it has a command) and the optional args field is present but not an array. StdioClientTransport expects args as an array of strings passed to the spawned command, so a non-array value (string, object, number) is a config error. The check uses hasOwnProperty so a missing args is fine (defaults to []), only a present-but-wrong-type args fails.

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 526360e320)

Solutions

  1. Wrap single arguments in an array: "args": ["--flag"] instead of "args": "--flag".
  2. Ensure every element of args is a string (no nested objects/numbers).
  3. If multiple args, list them as separate array elements: ["--port", "8080", "--verbose"].
  4. Remember args is optional — if there are none, omit the key rather than setting it to an empty non-array.

Example fix

// before
{
  "myServer": {
    "command": "npx",
    "args": "-y @modelcontextprotocol/server-filesystem /tmp"
  }
}

// after
{
  "myServer": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  }
}
Defensive patterns

Strategy: type-guard

Validate before calling

function validateStdioArgs(name, server) {
  if (Object.prototype.hasOwnProperty.call(server, 'args')) {
    if (!Array.isArray(server.args) || !server.args.every(a => typeof a === 'string')) {
      throw new Error(`MCP server '${name}': args must be an array of strings.`);
    }
  }
}

Type guard

/** @param {unknown} s */
function hasValidStdioArgs(s) {
  if (!s || typeof s !== 'object') return false;
  if (!('args' in s)) return true; // args optional
  return Array.isArray(s.args) && s.args.every(a => typeof a === 'string');
}

Try / catch

try {
  // start MCP stdio server
} catch (e) {
  if (/MCP server args must be an array/.test(e.message)) {
    throw new Error('Wrap MCP server args in an array of strings, e.g. ["--flag", "value"].');
  }
  throw e;
}

Prevention

When it happens

Trigger: A stdio MCP server config where args is a single string (e.g. "--flag") instead of ["--flag"], an object, a number, or any non-array. Determination as stdio happens because the entry has a command field.

Common situations: Writing args as a string instead of a one-element array — the single most common form; copy-pasting a CLI invocation as a flat string; JSON config authoring mistake; merging configs where args got coerced to a string.

Related errors

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