BoltAI MCP Tool-Call Hang: Technical Report

Date stamp: 260912 Reporter: Nigel Protter (existing Featurebase reports below) Scope: Local MCP filesystem server tool calls (write_file, edit_file) issued from an AI agent session running inside BoltAI on macOS.

1. Summary

Two distinct fault mechanisms were observed during a single BoltAI chat session using a local stdio MCP filesystem server. Both produce the same visible symptom: a tool call appears to stop progressing, with a "Continue" or "Continue generating" control appearing in the UI, and no corresponding tool-result content in the model-visible transcript.

2. Environment

• OS: macOS (build/version not captured in-session; to be supplied by reporter)

• BoltAI version/build: not captured in-session; to be supplied by reporter

• MCP server: local stdio filesystem server (custom, exposing write_file, edit_file, get_file_info, read_text_file, list_directory, among others)

• Model in use during observation: Claude (Sonnet), accessed via BoltAI's chat interface

3. Fault Mechanism A: Tool-Call Relay Hang

Sequence observed:

1. The model issues a tool call (e.g. edit_file) to the MCP server.

2. Screenshots of the BoltAI window show the tool-call block in a "Running tool: ..." state.

3. In at least one occurrence, that running-state block disappeared from the visible history entirely on the next screen state, replaced by a "Continue" or "Continue generating" control, with no result block and no error message rendered.

4. The model's own transcript contains no corresponding tool-result for that call — from the model's side, the call simply never returned.

5. Disk state was checked directly via a separate get_file_info call after the stall. In one occurrence the target file was confirmed unchanged (the write had not reached disk). In a separate occurrence in the same session, the stall occurred immediately after a trivial, already-completed read-only shell command, with no write pending at all, indicating the stall is not exclusively tied to write payload delivery.

4. Fault Mechanism B: Large-Payload Write Non-Return

Sequence observed:

1. A write_file call was issued with a content payload of approximately 11,000 characters (11 KB), targeting a new file.

2. The call entered a running state in the BoltAI UI and did not return a result for the remainder of the session turn.

3. No error was surfaced. No tool-result block was produced in the model's transcript for that call.

4. Directory listing after the stall confirmed the target file was never created on disk.

5. A control test was then run: a write_file call with a 4-byte payload to a new file. That call returned a success result immediately, and the file was confirmed present on disk via get_file_info.

This establishes that the write pathway is not universally blocked; the fault is correlated with, but not conclusively proven to be caused by, larger single-call payload size.

5. Escalation Test Log

A controlled escalation test was run: successive edit_file append calls of increasing size against a single target file, with get_file_info verification after each.

Step 4 indicates the same payload-size range that failed at Step 3 succeeded on other occasions in the same session, indicating the fault is intermittent rather than a deterministic size threshold.

6. Related Reports Already Filed

Two prior reports on the BoltAI Featurebase board (feedback.boltai.com), filed by this reporter, status "In QA" as of 260912:

1. "Local MCP server Tool-Call Loop Bug" (feedback.boltai.com/p/local-mcp-server) — describes the client failing to auto-relay a completed tool result back to the model to trigger the next turn, producing an apparent hang with no error, resolved only by the user typing a new message to force the client to package and send the pending tool result.

2. "Constant halts using MCP file/directory reads/writes/searches" (feedback.boltai.com/p/constant-halts-using-mcp-filedirectory-readswritessearches-per-this) — describes a serializer that validates JSON parameters before checking payload size, proposed as an architectural constraint affecting any tool using JSON parameter arrays for large payloads.

7. Client-Side Mitigation In Use

Pending a vendor-side fix, the following mitigation is in standing use on the reporter's side:

1. Write/edit payloads are kept under approximately 1,500 characters per call.

2. File state is verified via a separate metadata read after every write call, rather than relying on the returned success message.

3. When a tool-call block stalls or disappears with a "Continue"/"Continue generating" control, disk state is checked before assuming either success or failure, then the same chunk is retried if the write did not land.

8. Requested Diagnostic Information

1. Whether BoltAI's MCP client applies a payload size limit or timeout to tools/call requests, and if so, its value.

2. Whether the client logs tools/call dispatch and response events in a way accessible to the user (log file path), to confirm whether the request reaches the local MCP server process at all during a stall.

3. Whether a fix is in progress for the two linked reports, and an expected timeline.

9. Client Configuration Settings (Reviewed and Ruled Out as Cause)

The following BoltAI settings were in effect throughout all observations in this report:

• Context Policy: last N message pairs, set to 15 pairs.

• Agent Loop Control: set to 50 steps.

• Max Tokens: set to 8,000 (8k) per response.

Each setting was reviewed against the observed fault pattern and ruled out as the cause:

• Context Policy (15 pairs): a context-window truncation would surface as loss of earlier conversation content, not as a tool-call block silently vanishing mid-call with no result and no error.

• Agent Loop Control (50 steps): a step-ceiling would produce a hard, visible stop with a message indicating the loop limit was reached, not an unlabelled "Continue"/"Continue generating" control appearing after a single call.

• Max Tokens (8k): a token ceiling would truncate a long response body, not cause a hang immediately after a trivial read-only shell command with no pending write and no long output, as recorded in Section 5, Step 5.

None of the three settings produce the specific symptom observed (a tool-call block disappearing from the running state with no result, no error, and no visible cause), so the fault is attributed to the client's MCP tool-call handling layer rather than to session/response configuration.

10. Cross-Model Observation

The fault was first observed in an earlier session using Google Gemini 2.5 Pro as the model. The observations recorded in Sections 3-5 of this report were captured in a later session using Claude (Sonnet) as the model, with the same BoltAI client, the same local MCP server, and the same settings recorded in Section 9. The fault reproduced under both models. This rules out a model-specific cause and points to the BoltAI client's MCP tool-call handling layer (the relay/serializer between client and model, independent of which model is attached) as the fault location.