MCP local server config: 'connection closed' / 'Ignoring MCP config entry without type' with command string + args + env fields

Summary

Configuring a local stdio MCP server in opencode.jsonc the way it's documented in most MCP server READMEs (e.g. @datalens-tech/mcp) fails in OpenCode 1.18.14/1.18.15. Several different misleading errors appear depending on the exact shape of the config entry.

What I expected

Standard MCP server README config (from datalens-tech/datalens-mcp README):

{
  "mcp": {
    "datalens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@datalens-tech/mcp@latest"],
      "env": {
        "DATALENS_ORG_ID": "<org-id>"
      }
    }
  }
}

I expected this to be accepted (or at least a clear error message pointing at the correct schema).

What actually happened

None of the error messages point at the real fix. Observed errors in sequence:

1. With "type": "stdio" + command: "npx" + args + env:

Configuration is invalid at .../opencode.jsonc
Expected { readonly "type": "local", ... } | { readonly "type": "remote", ... }, got {...} mcp.datalens
Missing key mcp.datalens.enabled

2. With "type": "local", "enabled": true, command as array, env:

● ✗ datalens failed
      MCP error -32000: Connection closed

3. With "type": "local", "enabled": true, command as string + args:

▲ No MCP servers configured

and in logs:

message="Ignoring MCP config entry without type" key=datalens

Root cause / working config

OpenCode's actual schema (documented at https://opencode.ai/docs/mcp-servers/) differs from the generic MCP READMEs:

• command must be an array (["npx", "-y", "..."]), not a string with a separate args field
• environment variables go under environment, not env
• "type": "local" (not stdio)
• timeout is helpful since npx first fetch can exceed the default 5000ms

Working config:

"mcp": {
  "datalens": {
    "type": "local",
    "command": ["npx", "-y", "@datalens-tech/mcp@latest"],
    "environment": {
      "DATALENS_ORG_ID": "<org-id>"
    },
    "enabled": true,
    "timeout": 30000
  }
}

After this, opencode mcp list shows datalens connected and list_commands works.

Suggested improvements

1. Validate config with a clear message instead of the misleading "Ignoring MCP config entry without type" when command is a string.
2. Accept the common README shape (command string + args) or auto-coerce it, since it's the de-facto standard in MCP server docs.
3. Emit a deprecation/helper message when env key is used instead of environment.

Environment

• OpenCode 1.18.15 (Debian package, TUI)
• Linux, x86_64
• Config path: ~/.config/opencode/opencode.jsonc

Reported by: Igor Golov (igor.programmer@gmail.com)