[FEATURE]: No way to start SDK server without loading user MCP servers

[kud]

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

When using @opencode-ai/sdk to embed OpenCode programmatically (e.g. a CLI tool that makes a one-shot model call), the server always loads all MCP servers from the user's ~/.config/opencode/opencode.jsonc at startup. There is currently no way to prevent this.

Why this matters

The GitHub Copilot API hard-caps tool count at 128 tools. A power user with many MCP servers can easily exceed this, causing a HTTP 400 error from the API:

Error: 400 Bad Request — tools count exceeds maximum allowed (128)

What was tried

1. Passing enabled: false via OPENCODE_CONFIG_CONTENT

const client = await createOpencode({
  config: JSON.stringify({
    mcp: {
      github: { enabled: false },
      playwright: { enabled: false },
      // ... all user MCPs
    }
  })
})

Result: All MCPs still connect at startup. The enabled: false config is silently ignored.

2. Disconnecting after startup (current workaround)

const client = await createOpencode({ ... })

const statusResult = await client.mcp.status()
const mcpNames = Object.keys(statusResult.data ?? {})
await Promise.all(mcpNames.map(name => client.mcp.disconnect({ name })))

const session = await client.session.create({ ... })

This works (MCPs end up "status": "disabled"), but is wasteful — every MCP connects then immediately disconnects on every invocation.

Requested change

Please add one of:

1. A startup option — e.g. createOpencode({ mcp: false }) to skip loading user MCPs entirely
2. Fix enabled: false in config — honour it at startup when passed via OPENCODE_CONFIG_CONTENT
3. A noMcp flag on the server or session level

Note on potential duplicates: #17605 and #4525 address project-level MCP overrides. This request is specifically about SDK/embedded use — programmatic consumers that should not inherit the user's global MCP config at all.

Environment

• @opencode-ai/sdk v1.3.7
• API: @opencode-ai/sdk/v2
• Provider: github-copilot/gpt-4.1

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• The issue does not use one of the required templates (Bug Report, Feature Request, or Question). Feature requests must use the Feature Request template, which requires a verification checkbox and a proper description field. The title should also start with [FEATURE]: instead of [SDK].

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

---

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: MCP config isolation — allow projects to opt out of global MCP inheritance #17605: MCP config isolation — allow projects to opt out of global MCP inheritance (very similar: both request a way to prevent global MCP servers from loading in a given context)
• [FEATURE]: Allow per-project MCP enabled/disabled overrides #4525: Allow per-project MCP enabled/disabled overrides (closed, but addressed the same core problem of selectively disabling MCPs at startup)

If you believe this was flagged incorrectly, please let a maintainer know.

[kud]

Workaround (until this is fixed in the SDK)

For anyone hitting this, here's what we ended up doing in @kud/ai-conventional-commit-cli:

Before calling createOpencode(), temporarily redirect XDG_CONFIG_HOME to a temp directory containing a minimal opencode/config.json with an empty MCP section. Since the SDK spawns opencode serve with { ...process.env } at call time, the child process picks up the isolated config and starts with zero MCP servers.

import { mkdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

// Create isolated config: <tmp>/aicc-<pid>/opencode/config.json
const isolatedDir = join(tmpdir(), `aicc-${process.pid}`, 'opencode');
mkdirSync(isolatedDir, { recursive: true });
writeFileSync(join(isolatedDir, 'config.json'), '{"mcp":{}}');

const originalXDG = process.env.XDG_CONFIG_HOME;
process.env.XDG_CONFIG_HOME = join(tmpdir(), `aicc-${process.pid}`);

try {
  opencode = await createOpencode({ signal, port });
} finally {
  if (originalXDG === undefined) delete process.env.XDG_CONFIG_HOME;
  else process.env.XDG_CONFIG_HOME = originalXDG;
}

This works on macOS and Linux where opencode respects XDG_CONFIG_HOME. It's a bit of a hack but eliminates the overhead of connecting/disconnecting all user MCP servers on every CLI invocation.