Hmbown/CodeWhale · error

MCP config exceeds the 1 MiB limit

Error message

MCP config exceeds the 1 MiB limit

What it means

MCP configuration files are capped at 1 MiB (`MAX_MCP_CONFIG_BYTES`). Before atomically writing a mutated config, the library re-serializes it and bails if the rendered JSON would exceed the limit, protecting against unbounded config growth and pathological file sizes.

Solutions

1. Remove unused or duplicate MCP server entries to shrink the config
2. Move large data (long args, big env payloads) out of the config — e.g. into scripts or environment files referenced by name
3. Split servers across project vs user scope configs instead of one file
4. If the config was already over the limit, hand-edit the file to a valid subset before re-running mutations

Example fix

// before
"env": {"BIG_BLOB": "<2 MB of inline data>"}
// after
"env": {"BIG_BLOB_FILE": "./blobs/big.txt"} // keep the payload out of mcp.json

const MAX_MCP_CONFIG_BYTES: u64 = 1_048_576;
let rendered = serde_json::to_string_pretty(&raw)?;
if rendered.len() as u64 > MAX_MCP_CONFIG_BYTES {
    eprintln!("config too large: {} bytes", rendered.len());
}

match mutate_config(path, None, edit) {
    Ok(r) => r,
    Err(e) if e.to_string().contains("1 MiB limit") => {
        prune_unused_servers(&mut cfg)?;
        mutate_config(path, None, |_| Ok(pruned)) // retry after shrinking
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling an MCP config mutation function (add/update server, consent history writes) whose resulting pretty-printed JSON exceeds 1,048,576 bytes on write (crates/tui/src/mcp.rs:5867).

Common situations: Adding hundreds of MCP servers to one config; pasting very large env var blobs or long argument lists into a server entry; a sync tool duplicating entries on every run until the file balloons.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• MCP consent history exceeds size limit
• project config exceeds the 1 MiB limit
• project hooks file exceeds the 1 MiB limit
• bundle at is bytes; the limit is bytes
• config file exceeds the 1 MiB limit

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/14b2df91e57f92d1. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/mcp.rs:5867

        if legacy {
            let object = raw
                .as_object_mut()
                .context("MCP config must be an object")?;
            let servers = object.remove("mcpServers").expect("checked above");
            object.insert("servers".into(), servers);
        }
        apply_json_delta(&mut raw, &before, &after);
        if legacy {
            let object = raw
                .as_object_mut()
                .context("MCP config must be an object")?;
            if let Some(servers) = object.remove("servers") {
                object.insert("mcpServers".into(), servers);
            }
        }
        let rendered = serde_json::to_string_pretty(&raw)?;
        if rendered.len() as u64 > MAX_MCP_CONFIG_BYTES {
            anyhow::bail!("MCP config exceeds the 1 MiB limit");
        }
        write_atomic(path, rendered.as_bytes())?;
        Ok((result, config_revision(Some(&rendered))))
    })
}

fn mcp_template_json() -> Result<String> {
    let mut cfg = McpConfig::default();
    cfg.servers.insert(
        "example".to_string(),
        McpServerConfig {
            command: Some("node".to_string()),
            args: vec!["./path/to/your-mcp-server.js".to_string()],
            env: HashMap::new(),
            cwd: None,
            url: None,
            transport: None,
            connect_timeout: None,

View on GitHub (pinned to 73e0f67d83)