MCP Message Tools¶
These tools let a model find messages in a channel and see why one failed. They use the same search the console's message search uses, and return only messages in channels the signed-in user can view.
search_messages¶
search_messages searches one channel's messages and returns the matches: each message's id, its source id, its queue, the node it is at and its time. A search can use:
| Condition | Argument |
|---|---|
| Queue | queue: inbound, processing, outbound, error or completed |
| Date range | from and to, ISO 8601 times with their offset, such as 2026-10-11T08:00:00Z |
| Source ids | sourceIds: up to 250 source message ids; the search returns the messages of those source messages, as the console's Source ID condition does |
| A node's value | nodePath and value, with valueRegex and valueInverted |
| Error text | errorContains |
At most limit matches are returned, up to the Max Page Size on the Model Context Protocol (MCP) page. The result also says how many messages were searched and whether the limit was reached.
While Return message content is off, a search can use only the queue, the date range and source ids, because the other conditions look inside the messages; one that uses them is refused. The matches then carry no message text. While it is on, each match also carries the snippet the console shows, and the search is recorded in the MCP audit log as a content read.
A search runs at most the Message Search Timeout (seconds) set on the Model Context Protocol (MCP) page, 30 by default. A search that runs longer is asked to stop and the call says so; the database may still be finishing it, so narrow the date range or the queue and try again.
get_message¶
get_message returns one message's metadata: its source, queue, node and message type, when it was created, and whether it is in error. It never returns the message body.
get_message_error¶
get_message_error returns why a message is in error: the node it failed at, when, and the error. The error keeps the exception classes and the code locations, and drops the exception messages other than the engine's own verbose error text, because a message from a failing script can quote the message itself. The engine log has the full text.
get_message_content¶
get_message_content returns one message's body, its response, or the original source message (part), in parts under the Read Cap (bytes) setting. It works only while Return message content is on, and every call is recorded in the MCP audit log before it runs, with a content read entry naming the message.
The body is returned as text the way the console's message view shows it, and encoding says how it was read: the character set QIE finds in the body (such as UTF-8 or WINDOWS-1252), ISO-8859-1 when it finds none, which reads one character per byte and covers plain ASCII and ISO 8583 messages, or dicom_json for a DICOM message, which is returned as its tags in JSON. A source message is read in the channel's own format.
Working the error queue¶
These tools change what happens to messages, so they need a token approved for Read and manage, no configuration changes or Full access: change configuration as you can in the console, and rights in the channel's zone: manage rights for resubmitting and discarding, and manage or errors-only rights for resolving.
| Tool | Does | Asks the person first |
|---|---|---|
resubmit_message |
Sends one source message through the channel again, unchanged | No |
resolve_error |
Resolves one errored message: its source goes through the channel again from the start, and its errors are marked completed | No |
resubmit_edited_message |
Resubmits one source message with new content | Yes |
resolve_edited_error |
Resolves one errored message with new content in place of its source | Yes |
resubmit_messages |
Resubmits a list of source messages, oldest first | Yes |
resolve_errors |
Resolves a list of errored messages, oldest first | Yes |
resolve_all_errors |
Resolves every errored message of the channel | Yes |
discard_messages |
Marks listed messages, or every message in one queue, completed without sending them | Yes |
purge_messages |
Deletes the channel's stored messages and errors older than a number of days, or every message of a stopped channel; administrators only | Yes |
A message that has been sent again cannot be recalled downstream, which is why everything but a single unchanged message asks the person first (see Confirmations). Sending the same single resubmit or resolve again within a minute returns the first answer instead of sending the message twice.
No tool resubmits a whole queue. To send completed messages again, find them with search_messages and pass their source ids to resubmit_messages. A source id is a match's sourceId, not its message id. A message sent to several destinations has one match per destination, all with the same source id, and the source is sent once.
Every list tool uses each id once, however many times it is listed, and counts it once in the question it asks and in its answer. resolve_errors and discard_messages refuse a list that names a message not in the queue they work on, and say which, so the person approves only messages that are in that queue when asked. The count in the answer is the number the person approved, not the number that ran. A message that leaves the queue while the person is answering, for example because someone resolved it in the console, is skipped when the run reaches it.
resolve_errors counts the errored messages listed, not the source messages it sends. It sends each source once, however many of its errored messages are listed, and sending a source resolves every errored message of that source, listed or not. For example, a message that went to two destinations and failed at both has two errored messages: listing both counts 2 and sends the source once. resolve_error and resolve_edited_error also resolve every errored message of the source. resolve_error and resolve_errors cannot send a source that failed in the preprocess script, whose content was purged or whose streamed file is gone. Its errors stay in the error queue; resolve_error answers with the reason, and for resolve_errors the channel log records it.
A whole-queue resolve or discard asks about the number of messages it found, and does nothing if that number has changed by the time the person answers, so the person approves exactly what runs.
Edited content is never recorded; the MCP audit log records only that the content was edited.
The list, queue and channel forms run in the background. get_bulk_operation_status shows how far a run has got, and stop_bulk_operation stops it; messages sent before the stop stay sent. cancel_purge stops a purge that is running, for administrators. None of these three asks the person, because stopping is the safe direction.