`tools/list` fails on Claude Code 2.1.234

[lunaynx]

What happened

I'm using Claude Code 2.1.234, and it fails to discover the tools.

Acccording to GPT-5.6 Sol, this is the issue:

agent-workspace-linux overrides ServerHandler::list_tools() itself, and currently returns:

Ok(rmcp::model::ListToolsResult::with_all_items(tools))

after sanitizing the generated schemas.

That used to be fine, but with MCP 2026-07-28, tools/list results require ttlMs and cacheScope. The Rust SDK deliberately models them as optional for backwards compatibility, so with_all_items() alone leaves them absent. Claude Code's validator then rejects exactly those missing fields.

So the actual fix in src/server.rs is:

use rmcp::model::CacheScope;

// ...

Ok(
    rmcp::model::ListToolsResult::with_all_items(tools)
        .with_ttl_ms(0)
        .with_cache_scope(CacheScope::Private),
)

You could also use a positive TTL, e.g. 60_000, if they want Claude Code to cache the tool list. 0 means immediately stale/no useful caching and is therefore the safest behavior-preserving choice. Private prevents the cached tool list from being shared across authorization contexts.

Expected vs actual

• Expected: tools/list is successful
• Actual: tools/list fails with an error

Reproduction

Steps (commands / MCP tool calls) to reproduce:

1. Start Claude Code
2. Do /mcp
3. Select agent-workspace-linux
4. Attempt to reconnect and confirm it still fails

Environment

• Linux distribution + version: Arch Linux
• Desktop session: Headless, but have X11 and some GNOME stuff installed
• MCP host: Claude Code 2.1.234
• Started with a permission ceiling? none
• agent-workspace-linux version or commit: @agent-sh/agent-workspace-linux@0.3.1

doctor output

Paste the output of agent-workspace-linux doctor (redact any local paths you do not want public):

{
  "runtime": {
    "xvfb": {
      "ok": true,
      "detail": "/usr/bin/Xvfb"
    },
    "xephyr": {
      "ok": true,
      "detail": "/usr/bin/Xephyr"
    },
    "xauth": {
      "ok": true,
      "detail": "/usr/bin/xauth"
    },
    "xdpyinfo": {
      "ok": true,
      "detail": "/usr/bin/xdpyinfo"
    },
    "xprop": {
      "ok": true,
      "detail": "/usr/bin/xprop"
    },
    "window_manager": {
      "ok": true,
      "detail": "/usr/bin/openbox"
    },
    "xdotool": {
      "ok": true,
      "detail": "/usr/bin/xdotool"
    },
    "screenshot": {
      "ok": true,
      "detail": "/usr/bin/ffmpeg"
    },
    "clipboard": {
      "ok": true,
      "detail": "/home/luna/.local/bin/xclip"
    },
    "policy": {
      "bubblewrap": {
        "ok": true,
        "detail": "/usr/bin/bwrap"
      },
      "firejail": {
        "ok": true,
        "detail": "/usr/bin/firejail"
      },
      "unshare": {
        "ok": true,
        "detail": "/usr/bin/unshare"
      },
      "slirp4netns": {
        "ok": true,
        "detail": "/usr/bin/slirp4netns"
      },
      "preferred_mount_backend": "bubblewrap",
      "preferred_network_backend": "bubblewrap",
      "notes": [
        "bubblewrap enforces mount and network namespace isolation for launched apps"
      ]
    }
  },
  "viewer": {
    "host_display": {
      "ok": false,
      "detail": "missing DISPLAY and WAYLAND_DISPLAY"
    },
    "source_build_xkbcommon_x11": {
      "ok": true,
      "detail": "xkbcommon-x11: 1.13.2"
    },
    "host_opener": {
      "ok": true,
      "detail": "/usr/bin/xdg-open"
    }
  },
  "ready_for_x11_workspace": true,
  "ready_for_host_viewer": false,
  "blockers": [],
  "viewer_blockers": [
    "Start the MCP from a desktop session with DISPLAY or WAYLAND_DISPLAY, or use `mcp --headless` for hosts that must never open a viewer."
  ],
  "recommended_next_step": "Run `agent-workspace-linux workspace start`, then launch apps into the workspace."
}

Logs / screenshots

Agent-workspace-linux MCP Server

   Status:           ⚠ connected · tools fetch
                     failed
   Command:          agent-workspace-linux
   Protocol:         2026-07-28
   Args:             mcp --headless
   Config location:  /home/luna/.claude.json
   Capabilities: none
   Issue:
   Invalid result for tools/list: [
     {
       "expected": "number",
       "code": "invalid_type",
       "path": [
         "ttlMs"
       ],
       "message": "Invalid input: expected number, received undefined"
     },
     {
       "code": "invalid_value",
       "values": [
         "public",
         "private"
       ],
       "path": [
         "cacheScope"
       ],
       "message": "Invalid option: expected one of \"public\"|\"private\""
     }
   ]

[avifenesh]

Shipped in v0.3.2 — npm i -g @agent-sh/agent-workspace-linux (or @0.3.2) picks it up now.

Thanks for the report and for the fix in #69. The diagnosis was exactly right: rmcp models the SEP-2549 fields as Option with skip_serializing_if, so with_all_items left them off the wire and the 2026-07-28 validator had nothing to read.

I verified the published artifact rather than the build, since that is what you actually install — fresh npm install @agent-sh/agent-workspace-linux@0.3.2 in an empty directory, let its postinstall download the binary and check the .sha256 sidecar off the Release, then replayed your handshake against it:

initialize  protocolVersion: 2026-07-28 | serverVersion: 0.3.2
tools/list  resultType: complete | ttlMs: 3600000 | cacheScope: private | tools: 82

Two things that came out of your report beyond the fix itself:

• The smoke failure was not yours. scripts/mcp_non_headless_viewer_smoke.js asserted host_viewer_ready === true with no guard, so on a headless box it could only fail — nothing to do with your diff. It now skips with a one-line reason (test(smoke): skip the non-headless viewer smoke without a host display #71). scripts/integration_smoke.sh is clean on a headless machine again, so that checklist box is checkable next time.
• CI could not run on your PR. Fork pull requests never got a CodeQL analysis from default setup, while the ruleset required one, so fix(server): add MCP 2026-07-28 support #69 was green and approved and still needed an admin override. CodeQL now runs from a workflow (ci: run CodeQL from a workflow so fork pull requests get analyzed #70), which does run for forks — the next external PR gets the check like anyone else.

The 1h TTL over the 0 you suggested, for the record: tool_router() is static and control mode and the permission ceiling are enforced when a tool is called, not by filtering the list, so a cached list cannot go stale inside a process. 0 would have been correct too, just without the caching win.