# OpenCode Setup

Source checked: 2026-06-19
Official source: https://opencode.ai/docs/mcp-servers/

OpenCode supports remote MCP server configuration and OAuth flows. Use the current OpenCode docs before changing commands. OpenCode can prompt for OAuth automatically when the server is first used; `opencode mcp auth <server-name>` is a manual auth/recovery command, not a mandatory install step.

Recommended setup path:

1. Use OpenCode native MCP setup first: `opencode mcp add core https://core.gradien.ai/mcp`.
2. If the user wants a guided CLI walkthrough, run the setup CLI with `--harness opencode --yes`.
3. Prefer remote MCP plus OAuth. Do not paste long-lived connector keys into OpenCode config unless OAuth is impossible and the user explicitly approves that fallback.
4. After registration, verify with `opencode mcp list` or the current OpenCode MCP status command.
5. Only run `opencode mcp auth core` if OpenCode says Core is unauthenticated, auth is stale, or verification cannot load tools.
6. If `opencode mcp auth core` prompts `core already has valid credentials. Re-authenticate?`, choose No unless you intentionally need to replace credentials. Then return to verification with `opencode mcp list` or `opencode mcp debug core`.
7. If OpenCode still reports `needs_auth` after valid credentials, run `opencode mcp logout core`, then `opencode mcp auth core` once, and check the protected-resource metadata/scopes before retrying loops.
8. Verify Core tools after auth completes. If tools are missing, restart OpenCode or start a fresh OpenCode session.