🔍 Model Filtering

You can restrict which models mcp-opencode will expose and query using two environment variables. This is useful for capping access to a specific provider, or blocking expensive models from accidental use.

🔧 Variables

⚙️ How matching works

Each pattern is either:

• an exact model ID — anthropic/claude-sonnet-4-6, which matches only that model, or
• a provider wildcard — github-copilot/*, which matches every model from that provider.

The rules:

• If MCP_OPENCODE_MODEL_ALLOW is unset or empty, all models are allowed.
• If it is set, a model must match at least one allow pattern to be available.
• A model matching any block pattern is always rejected, even if it also matches an allow pattern. Block wins.

Both query and list_models respect these filters: blocked models never appear in the list, and querying one returns an error.

🔁 Job fallbacks

A headless job (task) tries [its model, ...MCP_OPENCODE_MODEL_FALLBACK] once each, in order (deduped). Fallback entries must pass the same allow/block filters; disallowed entries are dropped. MCP_OPENCODE_MODEL itself stays a single model and is unchanged.

A switch happens when the model is down: the session status stays retry continuously for at least MCP_OPENCODE_RETRY_TIMEOUT_SECONDS (default 90), or the run ends in a provider error (a provider.* error type, or model not found). Broken code or failing tests in the work are not "down". On a switch the watchdog interrupts the session, switches its model and re-prompts the same session with the same prompt on the next model, so history and worktree edits carry over; when the list is exhausted the job settles as error.

📝 Example

A config that allows only Copilot and Anthropic models, while blocking one specific Opus model:

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-opencode"],
      "env": {
        "MCP_OPENCODE_MODEL_ALLOW": "github-copilot/*,anthropic/*",
        "MCP_OPENCODE_MODEL_BLOCK": "anthropic/claude-opus-4-6"
      }
    }
  }
}

The active filter summary is included in each tool's description, so your assistant always knows which models it may reach for.