What causes "Expected a TOML array for MCP args" in upstash/context7?

Wrap the value in square brackets: args = ["--verbose"].

Expected a TOML array for MCP args

Error message

Expected a TOML array for MCP args

What it means

Thrown by parseTomlStringArray, the parser for the MCP server args value, when the value does not begin with '['. The MCP args field must be a TOML array of strings; anything else (bare string, inline table, number, etc.) is rejected at the first character check.

Solutions

Wrap the value in square brackets: args = ["--verbose"].
Make each argument its own quoted string element in the array.
Use an empty array args = [] when there are no arguments.
Verify the entry syntax against the documented [mcp_servers.*] schema.

Example fix

// before (config.toml)
args = "--verbose"
// after
args = ["--verbose"]

Defensive patterns

Strategy: validation

Validate before calling

function parseArgsValue(v) {
  const t = typeof v;
  if (t !== 'string') throw new Error('args must be a string of TOML source starting with [');
  if (!v.trimStart().startsWith('[')) throw new Error('args must be a TOML array');
}
parseArgsValue(argsSource);

Type guard

const isTomlArraySource = (v) => typeof v === 'string' && v.trimStart().startsWith('[');

Try / catch

try { parseConfig(toml); } catch (e) { if (e.message === 'Expected a TOML array for MCP args') { console.error('Wrap the args value in square brackets: args = ["..."]'); } else throw e; }

Prevention

Always write args as a bracketed array, even for a single argument
Use args = [] when there are no arguments
Copy the documented [mcp_servers.*] schema exactly
Validate the TOML structure before loading the config

When it happens

Trigger: Setting args to a non-array value in an [mcp_servers.*] section, e.g. args = "--verbose" or args = { a = 1 }, then invoking the parser/reader for that entry.

Common situations: Hand-writing the config and forgetting the brackets; converting from JSON where args was sometimes a bare string; a tool or script generating malformed TOML; misunderstanding that args must always be a list even for one argument.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of upstash/context7@4416fb855b (2026-09-16). Data as JSON: /api/errors/aa70772a46e7c66c. Report an issue: GitHub.

Appendix: source

Thrown at packages/cli/src/setup/toml-editor.ts:86

  }
  throw new Error("Unterminated TOML basic string in MCP args");
}

function parseTomlLiteralString(source: string, start: number): TomlStringToken {
  const endQuote = source.indexOf("'", start + 1);
  if (endQuote === -1) throw new Error("Unterminated TOML literal string in MCP args");
  const value = source.slice(start + 1, endQuote);
  if (value.includes("\n") || value.includes("\r")) {
    throw new Error("Multiline strings are not supported in MCP args");
  }
  return { value, start, end: endQuote + 1 };
}

function parseTomlStringArray(
  source: string,
  start: number
): { tokens: TomlStringToken[]; end: number } {
  if (source[start] !== "[") throw new Error("Expected a TOML array for MCP args");

  const tokens: TomlStringToken[] = [];
  let index = start + 1;
  while (index < source.length) {
    index = skipTomlArrayTrivia(source, index);
    if (source[index] === "]") return { tokens, end: index + 1 };

    const quote = source[index];
    if (quote !== '"' && quote !== "'") {
      throw new Error("MCP args must be a TOML array containing only strings");
    }
    if (source.slice(index, index + 3) === quote.repeat(3)) {
      throw new Error("Multiline strings are not supported in MCP args");
    }

    const token =
      quote === '"' ? parseTomlBasicString(source, index) : parseTomlLiteralString(source, index);
    tokens.push(token);

View on GitHub (pinned to 4416fb855b)