Reference

MCP tools

This page lists the tools and the resources of the Tiza MCP server, with their arguments, their replies and their errors. To add the server to a client, see Connect an agent.

The server

tiza mcp starts the MCP server on standard input and standard output. Your MCP client starts it for you.

• The server talks to the live instance through the local socket. Each tool sends one or more requests of the Socket API.
• --socket PATH and --session NAME select the instance, as for every command that uses the socket. See Connect.
• The server starts when no instance runs. Each tool call then fails until an instance listens.
• Each request opens a new connection. Thus a call goes to the instance that listens at that time.
• list_annotations and export_image send two requests. The screen can change between the two.
• At the start, the server sends instructions to the client: what Tiza is, when to use it, and the order of the calls.

Find the tools

A client can defer the tools. It then loads only the tool names and the instructions at the start. Claude Code does this with its tool search.

• These tools ask such a client to load them at the start: status, get_code, render_text and add_box. Their _meta has "anthropic/alwaysLoad": true.
• A client finds the other tools when it searches for what it wants to draw.
• A client that does not know the key ignores it.
• In Claude Code, the server entry can set alwaysLoad for all the tools of the server.
• With "alwaysLoad": false, the server entry defers all the tools of the server, these 4 tools included. This setting needs Claude Code v2.1.287 or later.

After you rebuild Tiza, the client keeps the old tool list. See After you rebuild Tiza.

Tools

The server has these tools. The third column names every socket method that each tool sends.

Read

Annotate

Change annotations

Moves

Steps

Focus and pointer

Theme and follow mode

Render and export

• export_image draws the export in the MCP server. The TUI does not draw it. See export_image.
• The socket methods with "None" in the MCP tool column have no tool. The resource tiza://scene gives the result of scene.get.

Arguments

The fields of each annotation type are in Annotations. The tables in this section give the names that the tools use.

Anchor

at, from and to take an anchor object. An anchor gives one place in the code.

• Give find, or line, or both. Without them, the tool fails with invalid_argument.
• occurrence counts the matches in reading order.
• With line and find, Tiza looks for the match of occurrence on that line first.
• When that line does not have it, Tiza looks in all the code. It then counts again from the top of the code.
• When the text is not in the code, the tool fails with text_not_found. Do not guess a column.
• When the column comes from an edge of the text that is inside a character, the tool fails with invalid_argument. Examples are a joiner alone in ad U+200D min, and a combining accent alone. highlight and add_mark use the two edges of the text, and an arrow end uses its start. The message names the character, its line and its column. Put the whole character in find, or use line and col. See A find inside a character.
• For highlight and add_mark, the anchor gives a span. With find, the span is the text. Without find, the span goes from col to the end of the line.
• For add_arrow, the anchor gives an arrow end: the first grapheme of the text, or col.
• The socket also takes end in an anchor. See Differences from the MCP tools. The tools send every key of an anchor to the socket. Thus end also works in an anchor of a tool, with line and col, and a key that the socket does not know fails.

Arguments of all the add tools

• A step of 0 becomes step 1.
• A step after 999 fails with invalid_argument.
• An annotation at a step after the last step makes that step.
• An arrow without a color gets the next color of the palette.
• An id that the document has already fails with duplicate_id. Give your own id. Then a second try of the same call does not add a copy.
• add_spotlight has no color.
• An unknown color name fails with invalid_argument.
• draw needs a stroke: a box, a callout, an arrow, or a highlight or a mark with the emphasis underline, brackets or strike. On another annotation, draw fails with invalid_argument.

Range

add_box, add_callout and add_spotlight take a range of lines.

• Give from_line, or give find_start and find_end together. Do not give the two forms in one call.
• find_start is the first match in the code. find_end is the first match after find_start, on the same line or on a later line.
• Thus a find_end of } is often the brace of an inner block. To put a box around a whole function, give its lines.
• A marker that matches nothing fails with text_not_found. The message names the marker.
• A marker gives only a line. Thus a marker that starts or ends inside a character works.
• The annotation keeps the two texts in markers.
• add_spotlight can have no range when it has ids.

Arguments of each add tool

• border and stroke take a stroke value. The default is solid.
• corners and route take rounded or sharp. The default is rounded.
• head_start takes a head value. The default is none.
• head_end takes a head value. The default is arrow. With none at the two ends, the arrow is a plain line.
• fill is true or false. A box has true as the default, and a callout has false.
• emphasis takes an emphasis value. The default is fill.
• placement takes margin, below or auto. The default is margin.
• width is the maximum width of the text of a callout, in columns. The text wraps at that width.
• The block is the widest line of text plus 4 columns.
• In the margin, width goes from 8 to the width of the margin minus 5. The default is 34.
• Below the code, width is at most the room under the code. The default is all that room.
• In the margin, a long title can make the block wider. Below the code, Tiza cuts a long title.
• kind is a kind, the name of a style, the name of a personal style of the config file of the instance, or any name when style has a glyph. list_kinds gives the personal styles in personal.
• style is a mark style for this mark only: glyph, legend and color.
• until is the last step at which a spotlight is active. Without it, the spotlight is active only at its step.

define_style

• A new style needs a glyph, unless its name is a built-in kind.
• When the style exists, the tool changes only the fields that you give.

update_annotation

id is required. Each other argument changes one part of the annotation. The annotation keeps all the parts that you do not give. The "Applies to" column replaces Type and Default, because every argument is optional.

• An argument that does not apply to the type of the annotation fails with invalid_argument. color and label are not in this rule.
• A spotlight stores a color and gives no error. add_spotlight has no color.
• A spotlight ignores label and gives no error. Nothing changes.
• An argument that the tool does not know fails. The reply names the arguments that it knows. text is not in this rule: see the next items.
• To change the text of a note, give label. For a callout, label changes the title.
• No tool changes the text of a callout. The socket method annotation.update can do it with shape. See Differences from the MCP tools.
• A text argument fails with a message that tells you to use label.
• A new place keeps the type, the kind, the style and the label of the annotation.
• A new from_line or to_line removes the markers of the annotation.
• With effect or emphasis, draw on an annotation without a stroke fails with invalid_argument.

Other tools

• The presenter can undo clear_annotations with u. The reply gives removed, remaining and revision.
• clear_annotations refuses "step": null and an unknown key. In its input schema, step is an integer, and the schema has "additionalProperties": false.
• add_move takes the fields of a move. See Moves. action has code.patch as the default.
• export_image has its own table. See export_image.
• point_at takes one of these forms: line; line and find; find; or from, with to as an option.
• find alone must be on one line of the code on screen.
• from without to points at the line from only.
• set_theme also takes the aliases of Agents and themes.
• set_theme with an empty string changes between dark and light. The theme name is not case-sensitive.
• goto_step with an id that no named step has fails with not_found.
• goto_step with a step after the last step fails with invalid_argument. It does not show the last step, as set_step does.
• goto_step to the step on screen puts the view of the step back. The view of a step comes from its last scroll, cursor or code.link move, also from an earlier step. The cursor and the view of the presenter go back to the line of that cursor or code.link move, or to the target of that scroll move. When the live pointer stays, the cursor stays on the pointer.
• goto_step with an id that is not a string or a whole number fails with invalid_argument.
• set_focus with from_line only puts one line in focus.
• set_focus with to_line only fails with invalid_argument.
• When the first line of the range is outside the code, set_focus fails with out_of_range.
• A last line after the end of the code becomes the last line.
• next_step after the last step goes to step 0 when the document has "loop": true.
• set_follow fails when the code is embedded and no followed file is known. See Agents and follow mode.
• At a step where a code.patch is applied, set_follow turns follow mode on paused. The reply gives paused, pending and resume_step.
• To know that Tiza read a save of the followed file, compare hash in the follow field of status with the sha256 of the file. A save of the same bytes does not change hash: then wait until reads increases. See Agents and follow mode.

Replies

Each tool replies with text. The text is JSON, except for the tools in this list:

• get_code gives the code, with a line number before each line. When a code.link shows a file, the first line is # VIEW. VIEW is the file, or FILE:A-B with a window.
• After the code, get_code gives a note for each line with invisible or control characters. An empty line and a first line, which starts with # The code above holds these characters, come before the notes. Each note names the characters of the line, for example # line 7: U+200D zero width joiner, col 1; U+2060 word joiner, col 4. col is the grapheme, counted from 0, as the col of an anchor. When the code has no such characters, get_code gives only the code. See Invisible characters in code.get.
• list_annotations gives the step label first, as # LABEL, for example # step 3/7 · Shared borrow. It leaves out this line when the label is empty.
• Then list_annotations gives one line for each annotation, or (no annotations).
• render_text gives the take. A second block of text names its width and tells you to give check the same width.
• The add tools and update_annotation give one sentence before the JSON.

In list_annotations, a line ends with (FILE) when the annotation belongs to a linked file. A line says (unanchored) when a move hides the annotation. A move that does not match the code any more comes last, as move #N … (stale: WHY).

In a text reply, a control character other than a tab or a line break shows as its picture, for example ␛, or as �. In a JSON reply, a control character is an escape, for example \u001b. DEL and a bidi control are escapes too. See Control and invisible characters.

status

status gives the result of the socket method status, plus a bridge object about the MCP server.

• binary_rebuilt, instance_build and hint are in the reply only when they apply.
• The fields of the socket method are in Fields of status.

Reply of an annotation tool

add_box, add_arrow, add_note, add_callout, highlight, add_mark, add_spotlight and update_annotation reply with the place of the annotation against the screen. The socket methods annotation.add and annotation.update give the same JSON.

visible is true when all these conditions are true:

• The step is reached.
• The file is on screen.
• The anchor is kept.
• The lines are in the window.
• For a note or a callout, the take at the width of the screen must also have room for the text.
• In supervised mode, Tiza makes the reply when the presenter accepts the change. Thus shown_step can differ from the step that you saw.
• The reply tells the state at one moment. The screen can change after it.
• A hidden annotation is not an error. Do not add it again.

The sentence before the JSON has one of these forms:

ID VERB at step N; visible now (the view is at step S).
ID VERB at step N; not visible now: the view is at step S and HIDDEN.

• VERB is added or updated.
• When the step has a title, step N becomes step N (TITLE).
• When the label is not complete, ; CLIPPED comes before the period of the first form.
• When the annotation appears at the next step, the second form ends with (next_step shows it). When it appears at a later step, it ends with (set_step N shows it).

For example:

a18 added at step 5; not visible now: the view is at step 0 and it appears at step 5 (set_step 5 shows it).

The hidden field has one of these messages.

The clipped field has one of these messages.

W is the width of the code area of the screen. check at that width gives the same result.

• The width of the code area is the terminal width less the side padding, from 20 to 400. For example, it is 98 in a terminal of 100 columns with the default padding.
• Before the instance knows the size of its terminal, the width is 100.

To make a label fit, make it shorter, or ask the presenter for a wider terminal.

Resources

The server gives these resources. A client that supports resources can attach them as context without a tool call.

• Each read asks the live instance. The server keeps no copy.
• When no instance listens, a read fails as a tool call fails.
• tiza://render.md starts with **NAME** (step N) when the instance shows a file. NAME is the name of that file.
• tiza://scene is a read. To change the document, use scene.put or scene.patch on the socket.

Errors

A tool fails in one of three ways.

• The server returns a JSON-RPC error. The error has a code and a message.
• The tool returns a result with isError: true. The text of the result is the message.
• The instance refuses the request. The server then returns a JSON-RPC error with the message and the socket code in parentheses, for example annotation zz does not exist (not_found).

The socket codes are in Error codes.

• ERROR is the error of the system, for example No such file or directory (os error 2).
• The message No Tiza instance is listening comes for each of these cases:
  • The server cannot connect to the socket.
  • The server cannot write the request.
  • The reply is not JSON.
• WHAT is tool NAME for a tool call, and resource for a resource read.
• failed to deserialize parameters: comes when an argument has the wrong type. It also comes when a required argument is missing or null.
• failed to deserialize parameters: also comes when update_annotation or clear_annotations gets an argument that it does not know. text of update_annotation gets its own message.
• failed to deserialize parameters: ends with the error of the parser, for example missing field `text` .
• The messages of export_image are in Errors of export_image.
• The server checks border, corners, stroke, route, the heads, emphasis, placement and the width of check itself. It sends no request for a bad value.
• These refusals of the server end with (invalid_argument), as a refusal of the instance does.
• An error about a value from a fixed set, such as color or border, does not repeat the wrong value. It gives the valid values. An error about a value of the wrong type repeats the value, cut at 40 characters.
• The width of render_text goes to the instance. The instance refuses a bad width with invalid_argument.
• Only update_annotation and clear_annotations refuse an argument that they do not know. The other tools ignore an unknown argument at the top level.
• A position argument (at, from or to) with a key that Tiza does not know fails, for example start instead of col. The error comes from the socket, with (invalid_argument) and the key that is near.
• add_move sends its arguments to move.add as the keys of the move. An argument that the action of the move does not use fails, for example align with a code.patch. When you do not give action, the action is code.patch.
• In add_move, a rebind entry with a key that Tiza does not know fails. For the socket, see Keys that Tiza does not know.
• Do not try again in a loop after rejected or internal. See Supervised mode.

See also

• Demo scenarios: ways to use the tools with an agent, for example a codebase tour or a review.
• A tour of tally: a tutorial that builds a tour of four files with the tools.