Mintplex-Labs/anything-llm · error · Error

MCP server command or url is required

Error message

MCP server command or url is required

What it means

Thrown when #parseServerType returns null, meaning the server definition has neither a recognized `type` (sse/streamable/http), nor a `command` property (stdio), nor a `url` property (http). The hypervisor cannot determine which transport to build, so it aborts before constructing a Client or transport. Each MCP server must declare either a stdio `command` or an HTTP `url`.

Source

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

        return new SSEClientTransport(url, {
          requestInit: {
            headers: server.headers,
          },
        });
    }
  }

  /**
   * @private Start a single MCP server by its server definition from the JSON file
   * @param {string} name - The name of the MCP server to start
   * @param {Object} server - The server definition
   * @returns {Promise<boolean>}
   */
  async #startMCPServer({ name, server }) {
    if (!name) throw new Error("MCP server name is required");
    if (!server) throw new Error("MCP server definition is required");
    const serverType = this.#parseServerType(server);
    if (!serverType) throw new Error("MCP server command or url is required");

    this.#validateServerDefinitionByType(name, server, serverType);
    this.log(`Attempting to start MCP server: ${name}`);
    const mcp = new Client({ name: name, version: "1.0.0" });
    const transport = await this.#setupServerTransport(server, serverType);

    // Add connection event listeners
    transport.onclose = () => this.log(`${name} - Transport closed`);
    transport.onerror = (error) =>
      this.log(`${name} - Transport error:`, error);
    transport.onmessage = (message) =>
      this.log(`${name} - Transport message:`, message);

    // Connect and await the connection with a timeout
    this.mcps[name] = mcp;
    const connectionPromise = mcp.connect(transport);

    let timeoutId;

View on GitHub (pinned to 526360e320)

Solutions

  1. For a local/stdio server, add a "command" array, e.g. "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"].
  2. For a remote server, add a "url" string and optionally "type": "sse" | "streamable" | "http".
  3. Remove empty/stub entries from mcpServers entirely if the server is not yet configured.
  4. Re-add the server through the AnythingLLM MCP UI so the schema is filled correctly.

Example fix

// before
"my-server": { "env": { "FOO": "bar" } }
// after (stdio)
"my-server": {
  "command": ["npx", "-y", "some-mcp-server"],
  "env": { "FOO": "bar" }
}
// after (http)
"my-server": { "url": "http://localhost:8080/sse", "type": "sse" }
Defensive patterns

Strategy: validation

Validate before calling

// Validate each definition declares a usable transport BEFORE booting.
const REQUIRED_ONE_OF = ["command", "url"];
const VALID_TYPES = ["sse", "streamable", "http"];
for (const { name, server } of hypervisor.mcpServerConfigs) {
  const hasType = VALID_TYPES.includes(server?.type);
  const hasTransport = REQUIRED_ONE_OF.some((k) =>
    Object.prototype.hasOwnProperty.call(server || {}, k)
  );
  if (!hasType && !hasTransport) {
    throw new Error(
      `MCP server "${name}" needs either a "command" (stdio) or a "url"/"type" (http)`
    );
  }
}

Type guard

function isStdioDef(s) {
  return !!s && Array.isArray(s.command) && s.command.length > 0;
}
function isHttpDef(s) {
  if (!s) return false;
  if (["sse", "streamable", "http"].includes(s.type)) return typeof s.url === "string";
  return typeof s.url === "string" && s.url.length > 0;
}
function isValidServerDef(s) {
  return isStdioDef(s) || isHttpDef(s);
}

Try / catch

try {
  await hypervisor.bootMCPServers();
} catch (e) {
  if (/command or url is required/i.test(e.message)) {
    logger.error(
      "One or more MCP servers lack a command/url. Inspect mcp_servers.json."
    );
  }
  throw e;
}

Prevention

When it happens

Trigger: An mcp_servers.json entry that is an empty object, or one that uses unrecognized keys (e.g. "cmd" instead of "command", "endpoint" instead of "url"). Also triggered if the entry exists but only has non-transport fields like env/headers.

Common situations: Following a tutorial that uses different key names; copying a config snippet that was truncated; migrating from an older config schema that renamed fields; leaving a stub entry while configuring.

Related errors

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