Problem
The tools/list response is ~256 KB (observed [262100 chars truncated] in the
Claude Desktop MCP log). 65 tools, each with long multi-paragraph descriptions plus
embedded _meta.ui.resourceUri / fastmcp metadata.
When a client is churning through reconnects (e.g. a cloud session reaching the local
stdio server over a device bridge), it re-fetches tools/list in a tight loop. A
quarter-megabyte payload re-sent dozens of times over a fragile transport is a
significant contributor to the "Unable to reach katana-erp-dev" failures a user sees
during long workflows — the operation lands server-side but the round-trip (or the
constant re-listing) fails to complete.
Observed live 2026-07-14: a ~100-tool-call built-bikes workflow over a cloud→Mac bridge;
server-side writes all succeeded (verified 9 MOs, no duplicates), but the client showed
repeated reach failures while re-pulling the 256 KB tool list.
Directions to explore
- Shorten tool descriptions. Many are multi-paragraph usage essays. Move the long
form to a resource / help doc and keep the tools/list description to a tight
sentence or two. Biggest single lever.
- Audit embedded
_meta. Every tool carries prefab UI + fastmcp tag metadata in the
list payload; confirm none of it is larger than it needs to be.
- Consider fewer top-level tools where several are thin variants that could collapse
behind one parameterized tool.
Acceptance
tools/list payload materially smaller (target: well under 100 KB).- No loss of the guidance agents actually rely on (move it to a resource if needed, not
delete it).
- A test or check that flags future tools/list-size regressions.
Not the whole story
This is an amplifier, not the root cause of the reach failures — the root is running a
cloud session against a local server over a device bridge. The durable fix there is to
run the workflow locally (Claude Desktop / on-computer) so there's no bridge. This issue
just makes the transport more forgiving when a bridge is in the path.
Problem
The
tools/listresponse is ~256 KB (observed[262100 chars truncated]in theClaude Desktop MCP log). 65 tools, each with long multi-paragraph descriptions plus
embedded
_meta.ui.resourceUri/fastmcpmetadata.When a client is churning through reconnects (e.g. a cloud session reaching the local
stdio server over a device bridge), it re-fetches
tools/listin a tight loop. Aquarter-megabyte payload re-sent dozens of times over a fragile transport is a
significant contributor to the "Unable to reach katana-erp-dev" failures a user sees
during long workflows — the operation lands server-side but the round-trip (or the
constant re-listing) fails to complete.
Observed live 2026-07-14: a ~100-tool-call built-bikes workflow over a cloud→Mac bridge;
server-side writes all succeeded (verified 9 MOs, no duplicates), but the client showed
repeated reach failures while re-pulling the 256 KB tool list.
Directions to explore
form to a resource / help doc and keep the
tools/listdescription to a tightsentence or two. Biggest single lever.
_meta. Every tool carries prefab UI + fastmcp tag metadata in thelist payload; confirm none of it is larger than it needs to be.
behind one parameterized tool.
Acceptance
tools/listpayload materially smaller (target: well under 100 KB).delete it).
Not the whole story
This is an amplifier, not the root cause of the reach failures — the root is running a
cloud session against a local server over a device bridge. The durable fix there is to
run the workflow locally (Claude Desktop / on-computer) so there's no bridge. This issue
just makes the transport more forgiving when a bridge is in the path.