{"record":{"id":"f9dcfc39d83558eb","repo":"Mintplex-Labs/anything-llm","slug":"mcp-server-definition-is-required","errorCode":null,"errorMessage":"MCP server definition is required","messagePattern":"MCP server definition is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/utils/MCP/hypervisor/index.js","lineNumber":450,"sourceCode":"        });\n      default:\n        return new SSEClientTransport(url, {\n          requestInit: {\n            headers: server.headers,\n          },\n        });\n    }\n  }\n\n  /**\n   * @private Start a single MCP server by its server definition from the JSON file\n   * @param {string} name - The name of the MCP server to start\n   * @param {Object} server - The server definition\n   * @returns {Promise<boolean>}\n   */\n  async #startMCPServer({ name, server }) {\n    if (!name) throw new Error(\"MCP server name is required\");\n    if (!server) throw new Error(\"MCP server definition is required\");\n    const serverType = this.#parseServerType(server);\n    if (!serverType) throw new Error(\"MCP server command or url is required\");\n\n    this.#validateServerDefinitionByType(name, server, serverType);\n    this.log(`Attempting to start MCP server: ${name}`);\n    const mcp = new Client({ name: name, version: \"1.0.0\" });\n    const transport = await this.#setupServerTransport(server, serverType);\n\n    // Add connection event listeners\n    transport.onclose = () => this.log(`${name} - Transport closed`);\n    transport.onerror = (error) =>\n      this.log(`${name} - Transport error:`, error);\n    transport.onmessage = (message) =>\n      this.log(`${name} - Transport message:`, message);\n\n    // Connect and await the connection with a timeout\n    this.mcps[name] = mcp;\n    const connectionPromise = mcp.connect(transport);","sourceCodeStart":432,"sourceCodeEnd":468,"githubUrl":"https://github.com/Mintplex-Labs/anything-llm/blob/3aec848f2885144aa8f1e53b9731a04310d5d558/server/utils/MCP/hypervisor/index.js#L432-L468","documentation":"#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.","triggerScenarios":"mcp_servers.json contains \"my-server\": null (or an explicitly undefined value) — the name exists but the definition object is absent.","commonSituations":"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.","solutions":["Remove the dangling key entirely, or restore its full definition object","Never use null as a placeholder for a server entry in JSON","Parse and validate the JSON (every value must be an object) before boot","Re-boot MCP servers after fixing the JSON"],"exampleFix":"// before\n{ \"my-server\": null }\n\n// after\n{ \"my-server\": { \"command\": \"npx\", \"args\": [\"-y\", \"server-memory\"] } }","handlingStrategy":"validation","validationCode":"function validateServerDefinitions(servers) {\n  for (const [name, server] of Object.entries(servers || {})) {\n    if (!server || typeof server !== 'object')\n      throw new Error(`MCP server \"${name}\" has no definition object`);\n  }\n}","typeGuard":"function isServerDefinition(server) {\n  return !!server && typeof server === 'object' && !Array.isArray(server);\n}","tryCatchPattern":"try {\n  await hypervisor.bootMCPServers();\n} catch (err) {\n  if (err.message === 'MCP server definition is required') {\n    // drop null-valued keys from the JSON and retry\n  }\n  throw err;\n}","preventionTips":["Never use null as a placeholder for a server entry — delete the key instead","Validate every value is an object before boot","Reject JSON merges that leave dangling keys"],"tags":["mcp","config-validation","required-field"],"backgroundTag":"missing-required-argument","analyzedSha":"3aec848f2885144aa8f1e53b9731a04310d5d558","analyzedAt":"2026-08-18T10:02:21.017Z","contentChangedAt":"2026-08-18T10:02:21.017Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}