MCP tool calls fail: invalid JSON when passing session_name / session_id (Cursor agent)

Summary

When driving libtmux-mcp from Cursor’s agent, some tool invocations fail before the Python server runs: the MCP layer rejects the request because the JSON payload for tool arguments is malformed.

This is not the same as the existing workaround for dict-shaped parameters sent as JSON strings (_coerce_dict_arg / Composer dict-stringification). Here, string values that must be JSON strings are emitted without quotes, producing invalid JSON.

Symptoms

Errors observed on the client/MCP bridge when calling tools that accept optional session targeting, for example:

• Unexpected token '$', "{"session_id": $10}" is not valid JSON
• Unexpected token 'c', "{"session_name": cv}" is not valid JSON

Valid JSON would require:

• "session_id": "$10"
• "session_name": "cv"

Impact

• Tools such as list_windows (with session_name / session_id) and select_window fail entirely; the agent falls back to shell tmux commands.
• Any tool parameter that is a string could theoretically hit the same class of bug if the serializer mishandles it.

Steps to reproduce (agent)

1. Use Cursor with the libtmux MCP server configured (stdio).
2. From the agent, call list_windows with session_name set to a bare session name (e.g. cv), or list_windows / related tools with session_id (e.g. $10).
3. Observe MCP parse/validation errors instead of a normal tool result.

(Exact UI steps depend on Cursor version; the failure is visible in the agent tool-call error output.)

Expected behavior

Tool arguments are serialized as valid JSON. String parameters are JSON-encoded (quoted, with proper escaping).

Actual behavior

The serialized arguments are not valid JSON (unquoted $10, unquoted cv), so the request fails at parse time.

Nature of the bug

• Likely location: MCP client / Cursor’s tool-argument serialization for this model or code path—not libtmux-mcp’s Python handlers (they never run).
• Relation to existing work: The project already documents dict parameters arriving as JSON strings (Composer 1/1.5) in _coerce_dict_arg and create_session.environment. This issue is orthogonal: it is invalid JSON at the wire level, not a semantic coercion problem.

Suggestions

1. Upstream: If reproducible only in Cursor, report or cross-link to Cursor with a minimal failing tool call payload.
2. Docs: Optionally note in MCP/client docs that agents should prefer globally unique pane_id targeting where possible to reduce reliance on session filters.
3. Investigation: Confirm whether FastMCP / MCP server can surface a clearer error when the client sends malformed JSON (may be outside server control).

Environment (observed)

• OS: Linux (WSL2)
• Cursor agent + libtmux-mcp MCP server (stdio)
• tmux sessions present (e.g. session name cv, id $10)

---

If maintainers prefer this tracked as documentation-only or upstream-meta, feel free to relabel; the goal is to capture the failure mode and distinguish it from _coerce_dict_arg-style workarounds.

Start by reproducing the Cursor agent calls to list_windows and select_window with session_name or session_id, and capture the malformed payload. Compare this behavior with the existing _coerce_dict_arg and create_session.environment handling; done means determining whether a repository-side error or documentation change is possible, or whether the failure belongs upstream to Cursor or the MCP client.