vercel/ai · error

Pi MCP server ${JSON.stringify(name)} must be configured wit

Error message

Pi MCP server ${JSON.stringify(name)} must be configured with an object value.

What it means

The Pi harness validates that each entry in the mcpServers configuration map is a plain object. Null, primitive, or array values cannot describe an MCP server, so the library throws this error naming the offending server key. It fails fast at session creation instead of producing a confusing failure later when the MCP server is started.

Source

Thrown at packages/harness-pi/src/pi-session.ts:1566

        harnessId: HARNESS_ID,
        specificationVersion: 'harness-v1',
        data: sessionFileName ? { sessionFileName } : {},
      };
    },
  };

  return sessionImpl;
}

function resolvePiMcpServers({
  mcpServers,
}: {
  mcpServers: Record<string, unknown> | undefined;
}): Record<string, unknown> {
  if (mcpServers == null) return {};
  for (const [name, value] of Object.entries(mcpServers)) {
    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
      throw new Error(
        `Pi MCP server ${JSON.stringify(name)} must be configured with an object value.`,
      );
    }
  }
  return mcpServers;
}

/**
 * Whether a terminal error (string from Pi's event stream, or a thrown error)
 * is an abort — the expected result of `doSuspendTurn` aborting the in-flight
 * turn. Only these are safe to swallow while `suspending`; any other error is
 * unanticipated and must surface as an `error` chunk.
 */
function isAbortError(value: unknown): boolean {
  if (value == null) return false;
  if (
    typeof value === 'object' &&
    (value as { name?: unknown }).name === 'AbortError'

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Change each mcpServers value to a plain object with the required fields (e.g. command, args, env).
2. Remove null/undefined entries from the map entirely instead of leaving empty placeholders.
3. Convert array-form server definitions into object form.
4. Validate the config with a schema (e.g. zod) before constructing the session.

Example fix

// before
createPi({
  mcpServers: {
    filesystem: null,
    fetch: ["npx", "-y", "mcp-server-fetch"],
  },
});
// after
createPi({
  mcpServers: {
    filesystem: { command: "npx", args: ["-y", "mcp-server-fs"] },
    fetch: { command: "npx", args: ["-y", "mcp-server-fetch"] },
  },
});

function validateMcpServers(servers) {
  for (const [name, value] of Object.entries(servers ?? {})) {
    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
      throw new Error(`MCP server '${name}' must be an object`);
    }
  }
}
validateMcpServers(config.mcpServers);

function isMcpServerConfig(v: unknown): v is Record<string, unknown> {
  return v != null && typeof v === 'object' && !Array.isArray(v);
}

try {
  await createPi({ mcpServers: config.mcpServers });
} catch (err) {
  if (String(err.message).includes('must be configured with an object value')) {
    const name = err.message.match(/Pi MCP server "([^"]+)"/)?.[1];
    throw new Error(`Fix mcpServers.${name}: must be an object with command/args`, { cause: err });
  }
  throw err;
}

When it happens

Trigger: Passing mcpServers where a value is null/undefined, a string or number, or an array — e.g. `{ mcpServers: { filesystem: null } }` or `{ mcpServers: { fs: ['node','mcp.js'] } }`. Triggered during session setup via the validation function called with the resolved mcpServers record.

Common situations: Copy-pasting a command-style array config (as some MCP launchers accept) into the Pi harness which expects an object with command/args/env fields; environment-driven config where an env var is unset and injected as null; YAML/JSON configs where an empty key collapses to null.

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

• ACP MCP server ${JSON.stringify(name)} must be configured wi
• maxRetries must be an integer
• maxRetries must be >= 0
• Invalid argument for parameter output: Invalid output type.
• Continuation maxAgeMs must be a positive integer.

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/147837f256207c42. Report an issue: GitHub.