[BUG] MCP tools connected but not exposed to agent

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 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

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-optimizer and lean-ctx servers - 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

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.

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.

@Necmttn

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.

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

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.

@timwkosatec

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):

opencode mcp list shows chrome-devtools ✓ connected
The MCP server process tree is alive (opencode -> cmd -> npx -> node chrome-devtools-mcp.js --autoConnect)
Chrome debug port is listening and reachable
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).
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.

@Start-Gao

I had similar issue as @Start-Gao, using chrome-devtools-mcp, but with OpenCode2:

Version: 0.0.0-next-17055 (next)
Date: 2026-08-09T15:06:25.595Z
OS: Windows 10.0.19045 (x64)
Terminal: [CMD on Windows Terminal]
Session ID: ses_018fa4385ffeQ6FM3Ax0D1XAL6
Model: opencode/deepseek-v4-flash-free

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

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:

Local stdio MCP server, registered in a workspace-local opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-server": {
"type": "local",
"command": ["node", "my-server.js"],
"timeout": 30000
}
}
}
Started via opencode serve (not the TUI), so the discovery result can be checked directly against the HTTP API rather than inferred from the agent's behavior.

Result:

GET /mcp → {"my-server":{"status":"connected"}}
GET /experimental/tool/ids → does not include any of the server's tools
GET /experimental/tool?provider=...&model=... → same, none of the server's tools appear

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.

@kitlangton

@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:

[BUG] MCP tools connected but not exposed to agent #33027 (this issue): local stdio MCP server shows connected, tools exposed correctly over the MCP protocol itself, but never surface via tool.ids()/tool.list() (confirmed independently by @Necmttn, @kungfusaini, @MaGnaL, and myself on v1.18.16/Windows).
[BUG] Subagents spawned via Task tool cannot execute MCP tools despite appearing in tool registry #16491: same symptom in the subagent/Task-tool path — tools appear in the registry but can't actually be invoked.
Docker MCP gateway connects but LLM cannot recognize/invoke the MCP server on macOS #26357: same symptom class (Docker MCP gateway), auto-closed by stale-bot without an actual fix — likely a duplicate, not resolved.

Two comments in this thread have already narrowed the likely cause:

@timwkosatec: MCP state appears scoped to the instance/working directory, so starting from a different path loses tool registration.
@Start-Gao: the failure is specific to the stdio subprocess path (CLI) — sidecar/HTTP-based servers (Desktop app) register fine.

This lines up with what I'm seeing: a locally spawned stdio server passes handshake and tools/list but 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.

Cross-platform confirmation with a tightly isolated repro, via opencode serve 1.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"} from GET /mcp for the entire run; zero MCP connection closed log lines during the observed window; the local servers verified working by direct stdio JSON-RPC tools/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):

session created 07:24 → permanently missing gmail_* (15) + gcalendar_* (9) for its whole lifetime, while gdrive_*, gitlab_*, fathom_* work fine.
sessions created later (08:11 via raw HTTP API, 08:37 via Paseo) → full tool set including all gmail_*/gcalendar_*.
An earlier session (06:35) was missing only gcalendar_* while using gmail_* 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/system overrides).

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. A ToolsChanged-driven invalidation (or per-prompt recompute) would fix all of them.

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:

❯ oc mcp list

┌  MCP Servers
│
●  ✓ fastmail connected
│      https://api.fastmail.com/mcp
│
└  1 server(s)

❯ oc mcp debug fastmail

┌  MCP OAuth Debug
│
●  Server: fastmail
│
●  URL: https://api.fastmail.com/mcp
│
●  Auth status: ✓ authenticated
│
●    Access token: SNIP
│
●    Expires: 2026-09-08T15:13:17.569Z 
│
●    Refresh token: present
│
●    Client ID: SNIP
│
◇  HTTP response: 401 Unauthorized
│
●  WWW-Authenticate: Bearer resource_metadata="https://api.fastmail.com/.well-known/oauth-protected-resource/mcp", scope="https://www.fastmail.com/dev/mcp"
│
●  Initial unauthenticated check returned 401, so this server requires OAuth
│
●  Testing OAuth flow (without completing authorization)...
│
◆  Connection successful (already authenticated)
│
└  Debug complete

I'm clearly authenticated and have repeatedly logged out / logged back in, but it still won't show MCP tools in session context.

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/ids and tool.list never include that server’s tools
The agent therefore cannot call them (Model 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?

I can reproduce this on macOS with opencode v2.0.8 in 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:

the custom val agent prompt is applied;
the capture model is reached successfully;
the provider request has no tools field / tool definitions;
a deterministic direct MCP check confirms the stdio server exposes five valid tools;
opencode mcp list reports no configured MCP servers for this inline standalone configuration.

I also tested a private OPENCODE_CONFIG file. 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.8 indicates MCP tools default to Code Mode; denying execute removes the synthetic Code Mode tool, hence codemode: false above. 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.

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 𝕺𝖕𝖊𝖓𝕮𝖔𝖉𝖊

Navigation Menu

Repository navigation

[BUG] MCP tools connected but not exposed to agent #33027

Description

[BUG] MCP tools connected but not exposed to agent

Description

Steps to Reproduce

Expected Behavior

Actual Behavior

Investigation

Similar Issue

Environment

Workaround

Request

Plugins

OpenCode version

Steps to reproduce

Screenshot and/or share link

Operating System

Terminal

Root cause and workaround

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[BUG] MCP tools connected but not exposed to agent #33027

Description

Description

[BUG] MCP tools connected but not exposed to agent

Description

Steps to Reproduce

Expected Behavior

Actual Behavior

Investigation

Similar Issue

Environment

Workaround

Request

Plugins

OpenCode version

Steps to reproduce

Screenshot and/or share link

Operating System

Terminal

Activity

github-actions commented on Jun 19, 2026

Necmttn commented on Jun 21, 2026

kungfusaini commented on Jun 30, 2026

MaGnaL commented on Jul 3, 2026

timwkosatec commented on Jul 15, 2026

Root cause and workaround

Start-Gao commented on Aug 3, 2026

ArsenicBismuth commented on Aug 9, 2026

wangzhuangwei commented on Aug 14, 2026

wangzhuangwei commented on Aug 18, 2026

Lukas-Novak commented on Sep 7, 2026

rcdailey commented on Sep 8, 2026

wangzhuangwei commented on Sep 11, 2026

oliolafsson commented on Sep 19, 2026

thdxr commented on Oct 11, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions