[BUG] MCP tools connected but not exposed to agent

[userX570]

Description

[BUG] MCP tools connected but not exposed to agent

Description

MCP server pdfrag connects successfully and exposes 6 tools via tools/list, but the tools do not appear in the agent's available tool list. The server is working correctly (responds to MCP protocol, tools are valid), but something in the opencode pipeline isn't passing those tools to the agent.

Steps to Reproduce

1. Create a custom MCP server (Python, stdio transport)
2. Register in ~/.config/opencode/opencode.json:

   "mcp": {
     "pdfrag": {
       "type": "local",
       "command": "/Library/Frameworks/Python.framework/Versions/3.14/bin/pdfrag-mcp"
     }
   }

3. Run opencode mcp list → shows "connected" with green checkmark
4. Start opencode session → tools NOT available to agent

Expected Behavior

MCP tools should be available as first-class tools in the agent session after successful connection.

Actual Behavior

• Server connects successfully
• opencode mcp list shows "connected"
• MCP protocol handshake works (initialize, tools/list returns 6 valid tools)
• Tools do NOT appear in agent's available tool list
• Agent cannot call MCP tools

Investigation

1. Server works correctly: Verified with Python MCP client - server responds to initialize, tools/list, and tool calls
2. Server format matches working servers: Compared with token-optimizer and lean-ctx servers - same structure, capabilities, and tool definitions
3. No error logs: opencode logs show no errors related to pdfrag
4. opencode binary is compiled: Cannot inspect source directly, but binary analysis shows MCP tool registration code exists

Similar Issue

Found similar issue on hermes-agent: #41625 - "MCP tools discovered but not exposed to agent in TUI mode"

The suspected cause there is a race condition in the TUI startup path with a timeout that's too short for MCP discovery.

Environment

• OpenCode version: 1.17.8
• OS: macOS (darwin)
• Python: 3.14
• MCP transport: stdio (local subprocess)

Workaround

Use CLI or Python direct calls:

python3 pdf_rag.py query "question"

Request

Please investigate why MCP tools are not being exposed to the agent despite successful connection. This may be related to:

• Race condition in tool discovery (similar to hermes-agent #41625)
• Tool filtering logic
• Agent tool context initialization

Plugins

No response

OpenCode version

No response

Steps to reproduce

No response

Screenshot and/or share link

No response

Operating System

No response

Terminal

No response

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Docker MCP gateway connects but LLM cannot recognize/invoke the MCP server on macOS #26357: Docker MCP gateway connects but LLM cannot recognize/invoke the MCP server — same core symptom of MCP connecting successfully but tools not being exposed to the agent/LLM
• [BUG] Subagents spawned via Task tool cannot execute MCP tools despite appearing in tool registry #16491: Subagents spawned via Task tool cannot execute MCP tools despite appearing in tool registry — related MCP tools availability issue

If your issue is distinct from these (e.g., different transport, different failure mode), please add a note explaining how it differs.

[Necmttn]

MCP visibility needs a staged capability pipeline, not only "connected." Track each server through connected, initialized, tools_listed, tools_registered, agent_visible, and invocation_allowed.

When opencode mcp list says connected but the agent cannot see tools, diagnostics should show the missing stage, tool count, registration namespace, agent/session id, and any filtering reason. A regression can use a tiny Python stdio MCP with two tools and assert they appear in the model-visible tool inventory after successful tools/list.

---

Generated with ax.

[kungfusaini]

Facing the same issue.

Totally agree with @Necmttn
The connected status is very opaque. If I'm connected and my agents don't see the MCP tools, what does that even mean from a suer standpoint.

[MaGnaL]

Having probably the same issue with the mcp-atlassian server. Connection green, auth works, but no tools available in opencode.

[timwkosatec]

Root cause and workaround

On Windows/OpenCode 1.18.1, MCP state is scoped to the OpenCode instance directory. If OpenCode is started from a different working directory, /mcps can show an MCP as connected in one instance while the session prompt runs in another instance without its MCP tools. The model then reports Model tried to call unavailable tool.

The important part was using the session ID together with its actual directory:

opencode --session "<session-id>" "C:/Users/<user>/Documents/Auto-WE"

For a new session, start OpenCode from the correct directory:

opencode "C:/Users/<user>/Documents/Auto-WE"

Then enable the MCP in /mcps and send the prompt from that same instance. opencode mcp list starts a separate process and is not a valid check for the running TUI.

[Start-Gao]

Confirmed on Windows with the same symptom, plus a new data point that may help isolate the failing path.

Environment:

• OS: Windows 10.0.26200 x64
• opencode CLI: 1.18.11 (npm install, opencode.exe)
• chrome-devtools-mcp: 1.6.0 (stdio/local subprocess, launched via npx -y chrome-devtools-mcp@latest --autoConnect)
• Chrome running with DevToolsActivePort (127.0.0.1:12885)

Symptoms (exactly as reported):

1. opencode mcp list shows chrome-devtools ✓ connected
2. The MCP server process tree is alive (opencode -> cmd -> npx -> node chrome-devtools-mcp.js --autoConnect)
3. Chrome debug port is listening and reachable
4. BUT opencode debug agent build shows the agent tool list WITHOUT any chrome-devtools_* tools. The model cannot call them (Model tried to call unavailable tool).
5. No errors in ~/.local/share/opencode/log/opencode.log related to MCP registration.

Key new observation (same version, different mode):

• OpenCode Desktop app (also v1.18.11) runs opencode core as a sidecar HTTP service (spawning sidecar { url: 'http://127.0.0.1:55178' } per its main.log). After restart, all chrome-devtools MCP tools ARE registered and usable in the agent context. ✅
• opencode CLI (v1.18.11) uses the stdio local-subprocess path. After restart (same session, same directory D:\Workspace\Demo\test), MCP tools are NOT registered. ❌

This suggests the bug is in the stdio (local subprocess) MCP tool registration path, while the sidecar/HTTP path is unaffected.

Additional detail matching the Windows instance-scoping comment from @timwkosatec:
The session was created on 2026-07-11 under opencode 1.17.18 and is being resumed across restarts (opencode TUI restores the last session). Resuming that session never re-registers the MCP tools even though the MCP server itself connects fine.

Related PRs still open (none merged): #37684, #38533, #40013, #40062 — all touch MCP tool registry reconciliation but are not yet merged. Would appreciate maintainers taking a look at the stdio registration path specifically.