OpenCode v1.17.1 Released with Reference Usage Descriptions and MCP Bugfixes

Summary

With the release of OpenCode v1.17.1, the open-source coding agent framework introduces improved context control through detailed usage descriptions for agent references. The new version also fixes several critical bugs, including Anthropic fallback failures and setup crashes for Model Context Protocol (MCP) server clients. A desktop-specific issue with macOS auto-updates has also been resolved.

What happened

Reference Usage Descriptions: Developers can now specify descriptive usage details for references, helping agents dynamically select and manage context. These descriptions appear in the new documentation and can be hidden from @ autocomplete if needed.
MCP Timeout Support: MCP prompt and resource requests now respect server-configured timeouts, improving robustness when integrating external tools.
Critical Core Bugfixes:
- Deprecated reference config entries continue to load under the newer references config key for backward compatibility.
- The Anthropic fallback response system has been fixed to handle API errors correctly again.
- MCP servers that fail during client setup now shut down cleanly without leaving broken socket connections.
Desktop Improvements: The new desktop session flow features a dedicated /new-session route with draft tabs that preserve the prompt and project selection until the session is explicitly launched. Additionally, macOS auto-updates have been restored.

Why it matters

Context management and seamless tool integration via the Model Context Protocol (MCP) are essential for autonomous coding agents. By allowing developers to describe references more precisely, OpenCode helps agents make better decisions about which information is relevant to a given task, reducing context bloat and token waste. Fixing MCP setup failures and time-outs ensures a much more stable multi-tool coding environment in daily developer workflows.

Evidence

Official Release Notes: The GitHub release page for OpenCode v1.17.1 documents all changes in detail.
Documentation: The updated OpenCode Documentation outlines how to configure the new reference descriptions.
Developer Feedback: On X/Twitter, developer @LLMpsycho posted about the critical fixes for MCP setup stability and the Anthropic fallback.

Analysis

Introducing reference descriptions is a clear signal that coding agents must interact more intelligently with large codebases. Instead of blindly loading all files or tools, agents can now reason about the utility of a reference based on its description. Eliminating dead connections and respecting timeouts protects developers from frozen CLI terminals when external APIs or local MCP servers are slow to respond.

Practical Takeaways

Update Configuration: Update your OpenCode configuration to adopt the new references key and write clear, concise descriptions to improve the agent’s context retrieval.
Review MCP Timeouts: Check your local or external MCP server configurations to verify that timeouts are set appropriately to prevent hanging connections.
Upgrade to v1.17.1: Install the latest release via npm using npm i -g @anomaly/opencode or upgrade the desktop app. macOS users may need to reinstall manually once if the auto-update mechanism was completely broken in their current version.

Open Questions

Will the dynamic context selection based on reference descriptions lead to a measurable reduction in average token usage?
Is the macOS auto-update fix sufficient to recover older, broken desktop installations without manual user intervention?