When an MCP call fails, first distinguish a transport rejection, an application rejection and a missing response. An interrupted connection does not prove that a change did not happen. Read the affected state before issuing another write.
This reference complements the MCP contract and Claude setup guide. Contract source: the generated tool catalogue from build 10.0.626, reviewed on 19 October 2026. The verification gaps identified below are not passed runtime tests.
Situation, response and safe reaction#
| Situation | Documented error or response | Safe reaction | Follow-up check |
|---|---|---|---|
| Listener unreachable | No HTTP response; no MCP error code can be inferred | Check the application, server status, port and local address | Start with a read-only query |
| Wrong endpoint | HTTP 404 for /mcp/ instead of /mcp | Use the exact configured path | Check connection and tools/list |
| Missing or incorrect API key | HTTP 401 | Configure the correct Bearer header in the client | Test a read with the key; never log the key |
Browser request with Origin | HTTP 403 | Use a local MCP client | Check the handshake without a browser Origin |
| Missing session / protocol header | HTTP 400 | Initialise a session and use a protocol version accepted by the server | Check session headers and tool discovery |
| Write attempted in read-only mode | Tool absent from tools/list; direct call rejected | Use reads for analysis; enable writes only after deliberate approval | Read the available tool list again |
| Invalid argument schema | JSON-RPC -32602, error.data.code and error.data.field | Correct arguments against inputSchema | Inspect the field path; rejection occurs before the document model |
| Invalid date | isError: true, _meta.errorCode: invalid_date_format | Supply a supported date format | Read the affected activity before a corrected write |
| Application conflict at commit | Tool error with a conflict reason; automatic rollback under the contract | Explain the fixed date, calendar or resource conflict; do not relax constraints automatically | Compare tree and conflicts with the initial state |
| Function unavailable under the licence | For example, license_missing for licensed favourite functions | Check the function and licence; do not bypass the restriction | Offer only an available alternative |
| Session limit reached | JSON-RPC -32000 | Close your own unused sessions | Initialise again, then read state |
| Response lost after a write | No reliable success or failure evidence | Do not retry blindly; reconnect and inspect state | Compare UUID, changed fields, assignments and conflicts |
HTTP cases come from the product’s access-control documentation. Codes come from the developer contract; error responses do not all have the same structure. No unverified code is added for read-only rejection. On 19 October 2026, DE and EN tests on build 10.0.626 deliberately discarded a write’s response body. The next read found that duration had already changed from 16 to 32 hours. Without retrying, undo restored the initial tree. This tests handling of a lost response, not a server crash or every possible network interruption.
Handle protocol and tool errors separately#
A JSON-RPC error appears in error. An application rejection may instead return a normal JSON-RPC result containing isError: true. Check both levels. structuredContent describes successful outputs and does not replace error handling.
This deliberately invalid argument example belongs only on a test dataset:
{"name":"rillsoft_task_create","arguments":{"name":"Date check","start":"32.13.2020"}}The documented machine-readable code is invalid_date_format. The English runtime text in the existing contract evidence is:
Invalid value for 'start': '32.13.2020' - DD.MM.YYYY hh:mm or YYYY-MM-DDThh:mm is expectedHandle the code rather than matching the English sentence. The German page shows the German evidence. Messages follow the language of the running Rillsoft Project build; translating a website does not change the application’s language.
Approve changes before writing, and saving before file operations#
Before a change, establish the source file, target object and intended effect. Read the UUID from the current tree and show the proposed old and new values. Ask about missing durations, ambiguous people, unsuitable roles or unclear dates. Permission to connect does not decide these planning questions.
For an approved duration change, keep the steps separate; replace <TASK_UUID> with a UUID from the current tree:
{"name":"rillsoft_project_tree_get","arguments":{}}
{"name":"rillsoft_task_update","arguments":{"uuid":"<TASK_UUID>","durationHours":24}}
{"name":"rillsoft_project_tree_get","arguments":{}}
{"name":"rillsoft_project_conflict_list","arguments":{}}Each line is a separate tools/call parameter object. Only after checking the result and obtaining approval to save should you call rillsoft_project_file_save, or rillsoft_project_file_save_as with a confirmed absolute path for a new file. Overwriting is a separate decision. The project examples put these steps in context.
What undo reverses#
Under the contract, one mutating tool call creates one undo step. The application UI shares this history: an intervening manual edit may be the latest step. Never apply a guessed number of undo operations to an unknown state.
{"name":"rillsoft_history_undo","arguments":{}}
{"name":"rillsoft_project_tree_get","arguments":{}}
{"name":"rillsoft_project_conflict_list","arguments":{}}Compare the tree with the reference captured before the change. Check affected fields and successor dates. A successful undo response alone does not establish that every change in a longer conversation has been reversed. A project built through many calls requires multiple editing steps; the employee-assignment assistant can make several assignments in one step.
Saving, file changes and sessions have separate limits#
| Operation | Limit |
|---|---|
rillsoft_project_file_save / rillsoft_project_file_save_as | File access without an undo step. Undo in the document does not restore an earlier file on disk. |
rillsoft_project_create / rillsoft_project_file_open | A new command history starts; earlier steps belong to the previous dataset. |
discardChanges: true | Discards unsaved state during the relevant file/session operation; use only after approval is clear. |
rillsoft_portfolio_project_files_save | Saves included project files, not the .rpp portfolio file. |
| Ending an MCP session | No promise to undo or save the open document. |
| Changing views | May affect presentation state and the modified flag; restore the original view and do not save a pure analysis. |
Reset the analysis view before switching files. Test recovery exclusively on a copy: read the initial state, make one change, undo it and compare; separately save and reopen, then compare again. The documented walkthrough includes this file roundtrip. The test-copy replay on 19 October 2026, build 10.0.626, passed in both languages: undo restored the full tree, saving/reopening preserved activity data and cleared the previous history. Invalid dates and schema errors left the tree unchanged. A server crash during a change was not induced.
Procedure for an uncertain write outcome#
- Stop sending writes. Record the call, arguments and time without credentials.
- After reconnecting, identify the project that is actually open.
- Read the affected activity and its assignments. For a creation call, use the previous tree and any returned UUID to determine whether the object already exists; names alone are not unique.
- If state matches the intended result, do not write again. If unchanged, resolve the cause and obtain approval before a new attempt. If state remains unclear or differs partly, stop and show the discrepancy.
- After correction, check successor dates and conflicts; saving remains separate.
This is a state-verification procedure, not a promise of atomic retries. The Rillsoft Project product page explains product scope and licensing options.
- Product version
- Rillsoft Project 10.0.626
- Last verified
- 2026-10-19