OpenCode Configuration Mastery

Core Principles

1. Start minimal, add complexity — A valid config is just { "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4-5" }. Add more only when you need it.
2. Configs deep-merge — Global + project configs combine. Arrays concatenate. Objects merge with project-level winning conflicts.
3. OpenCode MCP ≠ Claude Desktop MCP — Different format. Root key "mcp", command as array, "environment" not "env", explicit "type" required.
4. Context budget is finite — Every MCP tool costs tokens. 50+ tools ≈ 67k tokens. Scope tools per-agent, use lazy loading, disable unused servers.

Quick-Start Recipes

"Set up OpenCode from scratch"

1. Create opencode.json in project root:

   { "$schema": "https://opencode.ai/config.json" }
   

2. Run opencode → use /connect to authenticate a provider
3. Pick your model: set "model": "provider/model-id" → See references/providers-and-models.md for all providers

"Add an MCP server"

Local (subprocess): "mcp": { "name": { "type": "local", "command": ["npx", "-y", "@pkg/name"] } }

Remote (HTTP): "mcp": { "name": { "type": "remote", "url": "https://mcp.example.com/mcp" } }

→ See references/mcp-servers.md for OAuth, tool management, all options → See references/plugins-and-ecosystem.md for trusted server catalog

"Add a custom/local model (Ollama, LM Studio)"

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "llama2": { "name": "Llama 2" } }
    }
  },
  "model": "ollama/llama2"
}

→ See references/providers-and-models.md for all local setups

"Add a plugin"

{
  "plugin": ["oh-my-opencode", "opencode-morph-fast-apply"]
}

→ See references/plugins-and-ecosystem.md for trusted plugin list

"Create a custom slash command"

Create .opencode/commands/my-command.md:

---
description: What this command does
input: optional
---
Instructions for the agent. User input available as $INPUT.

→ See references/agents-commands-rules.md for full format

"Lock down permissions"

{
  "permission": {
    "edit": "ask",
    "bash": { "*": "ask", "rm *": "deny", "git push *": "deny" },
    "webfetch": "deny"
  }
}

→ See references/agents-commands-rules.md for permission patterns

"Reduce context usage from MCP tools"

1. Disable tools globally, enable per-agent:

   {
     "tools": { "github_*": false },
     "agent": { "pr-reviewer": { "tools": { "github_*": true } } }
   }
   

2. Install lazy loader: "plugin": ["opencode-mcp-tool-search"]
3. Disable unused servers: "mcp": { "unused": { "enabled": false } }

Decision Trees

What to Configure

Need	Config Key	Reference
Pick a model	model, small_model	providers-and-models.md
Add LLM provider	provider	providers-and-models.md
Connect external tool	mcp	mcp-servers.md
Install plugin	plugin	plugins-and-ecosystem.md
Control what agents can do	permission	agents-commands-rules.md
Add reusable commands	.opencode/commands/	agents-commands-rules.md
Set project conventions	instructions	agents-commands-rules.md
Override agent model/behavior	agent	agents-commands-rules.md
Customize keybinds	keybinds	agents-commands-rules.md

MCP: Local vs Remote

Signal	Use Local	Use Remote
npx/uvx package available	✓
Vendor provides hosted endpoint		✓
Need OAuth authentication		✓
Air-gapped environment	✓
Docker-based server	✓
Want zero local install		✓

Provider Selection

Need	Provider	Auth
Best coding quality	Anthropic	/connect or API key
Budget-conscious	OpenCode Zen	/connect
Enterprise/compliance	Azure OpenAI, Bedrock	IAM + config
Offline/air-gapped	Ollama, llama.cpp	Local, no auth
Multi-model access	OpenRouter	API key
Existing subscription	GitHub Copilot	/connect

Security Checklist (Before Adding MCP Server)

☐ Known vendor or significant GitHub stars · ☐ Filesystem scoped to specific dirs · ☐ API keys use {env:VAR} · ☐ Unused servers disabled · ☐ Versions pinned (no @latest) · ☐ Permissions restrict dangerous tools → See references/plugins-and-ecosystem.md for OWASP MCP Top 10

Anti-Patterns

Pattern	Fix
"mcpServers" root key	Use "mcp" (OpenCode format)
"command": "npx" + "args"	Use "command": ["npx", ...] array
"env": {} for MCP	Use "environment": {}
Missing "type" on MCP	Add "type": "local" or "remote"
API keys in config	Use "{env:VAR_NAME}" substitution
50+ MCP tools globally	Per-agent scoping or lazy loading
@latest in MCP commands	Pin specific versions

Reference Files

File	Contents
references/config-schema.md	Full opencode.json schema, all top-level keys, file locations, precedence, merging, variable substitution, LSP/formatter config
references/mcp-servers.md	Local/remote MCP setup, OAuth, tool naming, per-agent scoping, CLI commands, quick-start examples for popular servers
references/providers-and-models.md	Provider setup, credentials, all major providers, custom/local providers (Ollama, LM Studio, llama.cpp), model selection
references/plugins-and-ecosystem.md	OpenCode plugins (oh-my-opencode, morph, etc.), MCP registries, community servers by category, OWASP security, context budget
references/agents-commands-rules.md	Agent config in JSON, custom commands, rules/instructions, keybinds, permission system, common profiles