Mintplex-Labs/anything-llm · error

MCP server definition is required

Error message

MCP server definition is required

What it means

#startMCPServer throws when the server half of the { name, server } pair is falsy. This means the MCP servers JSON has a named key whose value is null, undefined, or was written as an empty entry — the hypervisor cannot derive a transport from nothing.

Source

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

        });
      default:
        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);

View on GitHub (pinned to 3aec848f28)

Solutions

1. Remove the dangling key entirely, or restore its full definition object
2. Never use null as a placeholder for a server entry in JSON
3. Parse and validate the JSON (every value must be an object) before boot
4. Re-boot MCP servers after fixing the JSON

Example fix

// before
{ "my-server": null }

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

function validateServerDefinitions(servers) {
  for (const [name, server] of Object.entries(servers || {})) {
    if (!server || typeof server !== 'object')
      throw new Error(`MCP server "${name}" has no definition object`);
  }
}

function isServerDefinition(server) {
  return !!server && typeof server === 'object' && !Array.isArray(server);
}

try {
  await hypervisor.bootMCPServers();
} catch (err) {
  if (err.message === 'MCP server definition is required') {
    // drop null-valued keys from the JSON and retry
  }
  throw err;
}

When it happens

Trigger: mcp_servers.json contains "my-server": null (or an explicitly undefined value) — the name exists but the definition object is absent.

Common situations: Commenting out a config by nulling the value (JSON has no comments, so users null entries); partial edits that leave a dangling key; merge conflicts resolved by keeping the key and dropping the body.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• MCP server name is required
• MCP server type must have sse or streamable value.
• MCP server "${name}": missing required "url" for ${server.ty
• MCP server "${name}": invalid URL "${server.url}"
• MCP server args must be an array

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