Repository navigation
[BUG] MCP tools connected but not exposed to agent #33027
Description
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
- Create a custom MCP server (Python, stdio transport)
- Register in
~/.config/opencode/opencode.json:"mcp": { "pdfrag": { "type": "local", "command": "/Library/Frameworks/Python.framework/Versions/3.14/bin/pdfrag-mcp" } }
- Run
opencode mcp list→ shows "connected" with green checkmark - 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 listshows "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
- Server works correctly: Verified with Python MCP client - server responds to
initialize,tools/list, and tool calls - Server format matches working servers: Compared with
token-optimizerandlean-ctxservers - same structure, capabilities, and tool definitions - No error logs: opencode logs show no errors related to pdfrag
- 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 fix(app): wire desktop menu accelerators to renderer commands #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
Activity
github-actions commentedon Jun 19, 2026
This issue might be a duplicate of existing issues. Please check:
If your issue is distinct from these (e.g., different transport, different failure mode), please add a note explaining how it differs.
Necmttn commentedon Jun 21, 2026
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 listsays 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 successfultools/list.Generated with ax.
kungfusaini commentedon Jun 30, 2026
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 commentedon Jul 3, 2026
Having probably the same issue with the mcp-atlassian server. Connection green, auth works, but no tools available in opencode.
timwkosatec commentedon Jul 15, 2026
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,/mcpscan show an MCP asconnectedin one instance while the session prompt runs in another instance without its MCP tools. The model then reportsModel tried to call unavailable tool.The important part was using the session ID together with its actual directory:
For a new session, start OpenCode from the correct directory:
opencode "C:/Users/<user>/Documents/Auto-WE"Then enable the MCP in
/mcpsand send the prompt from that same instance.opencode mcp liststarts a separate process and is not a valid check for the running TUI.Start-Gao commentedon Aug 3, 2026
Confirmed on Windows with the same symptom, plus a new data point that may help isolate the failing path.
Environment:
opencode.exe)npx -y chrome-devtools-mcp@latest --autoConnect)Symptoms (exactly as reported):
opencode mcp listshowschrome-devtools ✓ connectedopencode debug agent buildshows the agent tool list WITHOUT anychrome-devtools_*tools. The model cannot call them (Model tried to call unavailable tool).~/.local/share/opencode/log/opencode.logrelated to MCP registration.Key new observation (same version, different mode):
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. ✅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 (
opencodeTUI 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.
ArsenicBismuth commentedon Aug 9, 2026
I had similar issue as @Start-Gao, using
chrome-devtools-mcp, but with OpenCode2:Note that this worked just fine some hours ago. And as the OpenCode auto-updates on startup, it might be possible the breaking changes happened during one of those updates.
Update: Just retested with opencode (v1), and it uses the MCP just fine. I wanted to revert back to older opencode2, alas any version before the latest always complain about missing some bun file:
The batch file cannot be found.Update 2: Opencode next (or v2) fixed this issue recently with the next-173xx). Unsure which version specifically.
Update 3: Opencode next failing again to use MCP with 0.0.0-next-17444
wangzhuangwei commentedon Aug 14, 2026
Can confirm this is still happening on a newer version than reported here (1.17.8) — reproduced today on 1.18.16, on Windows, so it's not something that got fixed in a recent point release.
Setup:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-server": {
"type": "local",
"command": ["node", "my-server.js"],
"timeout": 30000
}
}
}
Result:
So it's not just that the agent never calls the tools — OpenCode's own tool-listing endpoints never surface them either, even though the MCP status endpoint reports the server as connected. Raised the local server's timeout to 30s to rule out a slow-spawn/discovery-timeout race, no change.
This is blocking us from using standalone local MCP servers as a tool-integration path at all right now — happy to share a minimal repro server if useful.
wangzhuangwei commentedon Aug 18, 2026
@kitlangton bumping this with a cross-thread summary, since three separate issues seem to be converging on the same root cause and none have had maintainer input yet:
connected, tools exposed correctly over the MCP protocol itself, but never surface viatool.ids()/tool.list()(confirmed independently by @Necmttn, @kungfusaini, @MaGnaL, and myself on v1.18.16/Windows).Two comments in this thread have already narrowed the likely cause:
This lines up with what I'm seeing: a locally spawned stdio server passes handshake and
tools/listbut never reaches the agent-visible tool set, which points at a race or scoping bug in the stdio discovery pipeline specifically, not MCP transport in general.Given four independent reporters and a plausible root cause already identified, could this get a look? Happy to help narrow it further or test a patch if there's a branch — this is currently blocking a production MCP integration on our end.
Lukas-Novak commentedon Sep 7, 2026
Cross-platform confirmation with a tightly isolated repro, via
opencode serve1.18.27 (npm, Linux), driven by the Paseo orchestrator (0.7.2).Setup: 6 MCP servers in global
opencode.json(5 local stdio incl. three Google servers spawned from the same python script with different args:gmail,gdrive,gcalendar; plus one remote with OAuth). All six report{"status": "connected"}fromGET /mcpfor the entire run; zeroMCP connection closedlog lines during the observed window; the local servers verified working by direct stdio JSON-RPCtools/list+tools/call.Symptom: long-lived sessions permanently lose a subset of MCP tools. Two sibling sessions in the same serve process, same directory, same project/instance, same agent (
build), same model+variant (litellm/kimi-k3, reasoningEffort=max):gmail_*(15) +gcalendar_*(9) for its whole lifetime, whilegdrive_*,gitlab_*,fathom_*work fine.gmail_*/gcalendar_*.An earlier session (06:35) was missing only
gcalendar_*while usinggmail_*successfully — i.e. the frozen subset differs per session, matching a cache snapshotted at session/instance bring-up and never invalidated, as described in Desktop caches MCP tools at startup, never refreshes on reconnect #40015 (here reproduced server-side, not Desktop).Ruled out: provider/gateway trimming (fresh sessions get all 24 google tools through the same LiteLLM gateway, verified by the model enumerating and calling them; requests up to ~75k tokens unaffected), model variant, agent config, and the orchestrator payload (it passes no
tools/systemoverrides).Workaround: create a new session — full tool set returns. Affected sessions never recover.
This cluster (#33027, #40015, #16491, #26357) really looks like one root cause:
MCP.tools()serves connect-time cached defs (s.defs), and a session/instance snapshot of "available tools" is never recomputed when that cache changes. AToolsChanged-driven invalidation (or per-prompt recompute) would fix all of them.rcdailey commentedon Sep 8, 2026
I'd like to report that I'm seeing symptoms of this issue with the remote Fastmail MCP server. Here's the output of
opencode mcp debug fastmail:I'm clearly authenticated and have repeatedly logged out / logged back in, but it still won't show MCP tools in session context.
wangzhuangwei commentedon Sep 11, 2026
Still blocking production for us.
Pinned OpenCode SDK/server: 1.18.4 (Windows). We also reproduced this earlier on 1.18.16 with a local stdio MCP server.
GET /mcp→{"status":"connected"}GET /experimental/tool/idsandtool.listnever include that server’s toolsModel tried to call unavailable tool)We have had to route CAD/CAE MCP hosts through an OpenCode custom tool + stdio MCP client bridge instead of native MCP registration.
Is there a target release for a fix? If not, should consumers treat native MCP tool exposure to the agent as unsupported for now?
oliolafsson commentedon Sep 19, 2026
I can reproduce this on macOS with
opencode v2.0.8in standalone CLI mode using a local stdio MCP server.Minimal shape:
{ "agents": { "val": { "mode": "primary", "system": "..." } }, "mcp": { "servers": { "val-local": { "type": "local", "command": ["python3", "-m", "val.chat_mcp"], "environment": { "VAL_HOME": "<temporary>" }, "codemode": false, "disabled": false } } }, "permissions": [ { "action": "*", "resource": "*", "effect": "deny" }, { "action": "val-local_*", "resource": "*", "effect": "ask" } ] }The configuration is supplied through
OPENCODE_CONFIG_CONTENT; the command is:opencode run --standalone --agent val --format json "report the tool inventory"Observed behavior:
valagent prompt is applied;toolsfield / tool definitions;opencode mcp listreports no configured MCP servers for this inline standalone configuration.I also tested a private
OPENCODE_CONFIGfile. That reached the standalone process, but the runtime then advertised the full built-in inventory (edit,execute,glob,grep,question,read,shell,skill,subagent,webfetch,websearch,write) rather than the configured MCP tools, so it is not a safe workaround.A source trace of tag
v2.0.8indicates MCP tools default to Code Mode; denyingexecuteremoves the synthetic Code Mode tool, hencecodemode: falseabove. The remaining issue is that the inline standalone configuration still does not register the MCP server.This is a fail-closed integration, so I have not enabled built-ins or dropped standalone isolation as a workaround.
thdxr commentedon Oct 11, 2026
Thanks for the report! OpenCode 2.0 is now out and development is focused on V2, so we're closing issues filed against OpenCode 1. Please upgrade (
opencode upgrade --major, details: https://anoma.ly/notes/opencode-2-0), and if this is still relevant on 2.0, reopen this issue or open a new one with your 2.0 version.— from 𝕺𝖕𝖊𝖓𝕮𝖔𝖉𝖊