mcp: failed servers are indistinguishable from unconfigured ones for the agent

Summary

When a configured MCP server is in failed state it disappears completely from the agent's tool surface — the tool catalog and the session's MCP instructions context contain only connected servers, with no placeholder, error, or "configured but failed" marker anywhere. From inside a session, a failed server is literally indistinguishable from one that was never configured. The agent therefore never asks the user to reconnect; it concludes "not configured" and burns turns inventing workarounds. This is distinct from connection retry (tracked in #52237 / #53226): even a perfectly retrying client should tell the model that a configured server is currently down.

Environment

opencode version: v2.2.5
OS: Darwin 25.6.0 (darwin arm64)
Terminal: rio (TERM=rio, COLORTERM=truecolor)
Shell: /bin/zsh
Install/channel: latest
Active plugins: @cortexkit/aft-opencode, @cortexkit/opencode-magic-context, opencode-planning-with-files

Reproduction

Configure at least one remote MCP server (type: "remote") and confirm it connects: opencode mcp list → ✓ connected.
Cause a transient outage so its connect fails — e.g. drop DNS/VPN briefly. The server log then shows:
level=WARN message="mcp connect failed" server=<name> status.status=failed status.error="getaddrinfo ENOTFOUND <host>"
Restore the network. opencode mcp list still reports ✗ <name> failed: getaddrinfo ENOTFOUND ... (persisted state, no probe, no retry — see mcp: remote MCP servers that fail once are never retried until service restart #52237).
Start a fresh agent session and ask the agent to list its available MCP servers, or to use a tool from that server.

Expected Behavior

The agent's context should list configured-but-failed servers — at minimum one line per server (name, last error, "user can reconnect via /mcps") — so the agent asks the user to fix the connection. The agent is the only party in the loop that can notice the gap during use and surface it.

Actual Behavior

The session's tool catalog and MCP instructions context contain only connected servers. There is zero trace of the failed one: no entry, no error, no marker. opencode mcp list reports the failure correctly, but that is an operator-only surface the agent never sees.

Real-world impact observed

Two configured servers (one OAuth remote HTTP server, one uvx-launched local server) both latched failed on a transient DNS outage. Network recovered within minutes; the failed state persisted for 24+ hours across fresh sessions (✗ datadog failed: getaddrinfo ENOTFOUND mcp.datadoghq.com, ✗ atlassian failed: ... error resolving DNS ... pypi.org). Agents in fresh sessions reasoned "this integration is not configured" and escalated into credential-hunting the underlying REST APIs directly — dangerous workaround behavior we had to defend against with a hard project rule banning it.

Additional Context

The retry/recovery aspect is already tracked and intentionally out of scope here: mcp: remote MCP servers that fail once are never retried until service restart #52237 (remote fail-once-never-retry), mcp: local server not restarted after transport error #53226 (local stdio not respawned after exit), closed mcp: failed-at-init servers are never retried for the session lifetime #61105, mcp: remote server latched as failed after one transient DNS error (no retry/backoff) #62369, canonical MCP remote client has no transport-level retry on socket/connection errors #25287 (NOT_PLANNED), and MCP servers that fail to connect are never retried and silently disappear from the tool list #51437 (duped onto the retry tracker; its body also noted servers "silently disappear from the agent's tool list").
Minimal fix is independent of any retry policy: inject a notice for failed-but-configured servers into the agent's MCP context. During backoff windows the agent still needs to know the server exists and is down, and that the fix is user-side (/mcps reconnect).
Related secondary symptom (noted in mcp: failed-at-init servers are never retried for the session lifetime #61105): opencode mcp list echoes persisted state rather than probing, so it keeps saying failed long after the endpoint is reachable again.

Thanks for the detailed write-up. The request: when a configured MCP server is failed (or needs_auth), the agent's context should still say it exists and is down, with its last error and a hint that the user can reconnect it via /mcps. That way the agent stops treating it as unconfigured.

Right now this is intentional. The MCP instructions block only covers servers with tools the session can use, so a failed server is left out completely. That makes this a feature request rather than a bug, and maintainers will consider it.

In the meantime, a small plugin can add the notice. It reads the server statuses before each model request and adds a short system note for any server that isn't connected. It type-checks against @opencode/plugin on dev, but I haven't run it in a live session. One way to install it is to save it as a local plugin, e.g. .opencode/plugins/mcp-status-notice.ts in your project or the plugins/ folder of your global OpenCode config directory:

import { Plugin } from "@opencode/plugin"

export default Plugin.define({
  id: "mcp-status-notice",
  async setup(ctx) {
    await ctx.session.hook("context", async (event) => {
      const { data: servers } = await ctx.mcp.list({ location: { directory: ctx.location.directory } })
      const lines = servers.flatMap((s) =>
        s.status.status === "failed" || s.status.status === "needs_auth"
          ? [`- ${s.name}: ${s.status.status} (${s.status.error})`]
          : [],
      )
      if (lines.length === 0) return
      event.system.push({
        type: "text",
        text: [
          "<mcp_unavailable>",
          "These MCP servers are configured but not connected, so their tools are missing:",
          ...lines,
          "Do not treat them as unconfigured or work around them. Ask the user to reconnect them (/mcps).",
          "</mcp_unavailable>",
        ].join("\n"),
      })
    })
  },
})

Related issues:

feat(core): keep MCP tools after a dropped connection and reconnect on demand #62756: proposal to keep a server's tools after its connection drops, show the failure reason and reconnect when next used. It overlaps partly, but doesn't cover servers that failed on their first connect.
mcp: remote MCP servers that fail once are never retried until service restart #52237: remote MCP servers that fail once are never retried.
mcp: local server not restarted after transport error #53226: local stdio servers are not restarted after a transport error.
mcp: invalid server entries are silently dropped from config #55419: invalid MCP server entries are silently dropped from the config, a similar "silently missing" case.

Navigation Menu

Repository navigation

mcp: failed servers are indistinguishable from unconfigured ones for the agent #62973

Summary

Environment

Reproduction

Expected Behavior

Actual Behavior

Real-world impact observed

Additional Context

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

mcp: failed servers are indistinguishable from unconfigured ones for the agent #62973

Description

Summary

Environment

Reproduction

Expected Behavior

Actual Behavior

Real-world impact observed

Additional Context

Activity

opencodejr commented on Nov 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions