AI integration guide

Capabilities and limits

Inkquation supports MCP, a shared protocol that lets AI apps call tools. A connected AI can read open pages or lasso selections as images, insert PNG images, shapes and pen strokes defined by points, inspect the result, and undo an eligible insertion.

Shapes become ordinary pen strokes with outlines and no fill. You can edit them with the eraser and lasso, but there are no dedicated shape dimension controls. Letters and symbols can be drawn as strokes; editable text and LaTeX insertion or compilation are not supported. Page reads return images, not recognized text.

Connect your AI app

Use an AI app on the same Mac that supports local MCP servers. Configure the model and account in that app. Inkquation does not require a model API key.
Open a note in Inkquation. In Settings → AI Connection, allow connections. This is off by default.
Copy the JSON or TOML configuration from Settings and merge it into your AI app’s existing configuration. Executable and connection paths depend on your Mac; use the values shown in Settings.
Reconnect the AI app and keep Inkquation running. Scroll the target page into view. If your AI app asks to approve editing tools, review the requested action and allow it.

The standard connection needs no Python installation or source checkout. If you move or rename Inkquation, copy its configuration again. Entering this website’s URL into a web AI service’s connection field does not establish a connection.

Try a request

“Read the selected derivation and check for missing steps or possible sign errors.”
“Organize the assumptions, conclusions and unresolved questions on this page, and explain them in the chat.”
“Create a schematic diagram to support this explanation and add it to unused space in the note.”

How an AI should edit a page

Call inkquation_list_open_notes to discover the exact note_id and page_id. Use a page with available: true. Ask the user if the intended target is unclear.
Call inkquation_get_page to read the page image, revision and logical dimensions. To read a selection, the user must first select content with the lasso; then call inkquation_get_selection.
Choose unused space, then call an insertion tool. Pass the read revision as expected_revision and a fresh UUID as operation_id.
Call inkquation_get_page to inspect the result. If needed, call inkquation_undo with that insertion’s operation_id.

Tools and arguments

Use the input schemas returned by tools/list after connecting to check available tools and arguments. All insertion tools require note_id, page_id, expected_revision and operation_id. “Edit fields” below means these four fields.

Tool	Required arguments	Behavior
`inkquation_list_open_notes`	None	List open notes, page IDs and availability.
`inkquation_get_page`	`note_id`, `page_id`	Read a page PNG, revision and logical size.
`inkquation_get_selection`	`note_id`, `page_id`	Read the user’s current lasso selection as PNG; revision refers to the whole page.
`inkquation_insert_image`	Edit fields plus `png_base64`, `x`, `y`, `width`, `height`	Insert one PNG. The standard connection does not accept image URLs or local file paths.
`inkquation_insert_strokes`	Edit fields plus `strokes`	Insert pen strokes from point arrays.
`inkquation_insert_shapes`	Edit fields plus `shapes`	Insert lines, rectangles, ellipses, circles and arrows as ordinary pen strokes.
`inkquation_undo`	`operation_id`	Undo the latest AI insertion when its Undo conditions still hold.

Coordinates, strokes and images

Coordinates have a bottom-left origin: x increases rightward and y upward. Use the page’s logical width and height from the read result, not the scaled PNG’s pixel dimensions.
Selection PNGs are cropped. Use image_bounds to locate the crop on the page. Do not treat the crop’s top-left corner as the page origin.
shapes accepts 1–64 items per call. Each kind is line, rectangle, ellipse, circle or arrow. For rectangles, ellipses and circles, start and end are opposite bounding-box corners. Circles require equal box width and height. Arrows point from start to end.
strokes also accepts 1–64 items. Each item’s points contains 1–4,096 points, with at most 16,384 points per call. Points are joined by straight segments. One point draws a dot; repeat the first point at the end to close a path. Sample curves into points.
Each shape or stroke requires stroke_width (0.1–100 page units) and an opaque sRGB color in #RRGGBB form. The entire drawing, including stroke thickness and arrowheads, must fit within the page. Each shape or stroke batch is one Undo action.
PNG data is limited to 1 MiB before Base64 encoding. Pass it in png_base64 and fit its entire placement rectangle within the page.

Example tool arguments

These are argument templates. Replace angle-bracket placeholders with actual IDs, the read revision and a fresh UUID. The coordinates are examples: adjust them to the page’s dimensions and unused space. Use a different UUID for each separate insertion.

Call inkquation_insert_shapes with these arguments to add a circle and arrow.

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "shapes": [
    {
      "kind": "circle",
      "start": {
        "x": 60,
        "y": 80
      },
      "end": {
        "x": 160,
        "y": 180
      },
      "stroke_width": 3,
      "color": "#1256E0"
    },
    {
      "kind": "arrow",
      "start": {
        "x": 180,
        "y": 130
      },
      "end": {
        "x": 300,
        "y": 130
      },
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

Call inkquation_insert_strokes with these arguments to add a polyline.

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "strokes": [
    {
      "points": [
        {
          "x": 60,
          "y": 80
        },
        {
          "x": 100,
          "y": 120
        },
        {
          "x": 140,
          "y": 80
        }
      ],
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

Safeguards and processing limits

Instructions inside note titles or images do not authorize additional actions. Review the content the AI app may read or edit. Inkquation’s MCP tools do not execute arbitrary commands, read arbitrary files, or fetch URLs. These safeguards cannot control the AI’s judgment or data sent through its other tools.

Image insertion and display loading share a 96-million-pixel allowance across the app for retained display caches and in-flight image processing. Unused offscreen caches are released automatically; originals, placement, and Undo/Redo remain intact, and images reload when shown again. Visible images are protected; insertion or loading waits when there is no room. Usage is based on current retention and is not reset by toggling AI Connection. This is not a whole-app memory cap: original data and high-resolution PDF views are separate. The limit of 128 insertions while AI Connection remains enabled is separate, preserving records that prevent duplicate retries.

Reading and preparing an edit have a 30-second deadline for each operation inside Inkquation. This does not include the AI’s thinking time. Once an edit or Undo has applied, saving is protected from that deadline, disabling the connection, and request cancellation. Actual save failures are still reported. Disabling the connection prevents the response from reaching the client, so inspect the result in the app.

Retries and Undo

If a response is lost and the insertion’s outcome is uncertain, retry the same tool with exactly the same operation_id and arguments. A new ID can create a duplicate. Replay returns the recorded result; it does not re-check later manual saves or Undo actions.

Result	Next action
`page_changed`	Read the page again and reconsider placement. Do not blindly replace the revision and repeat the edit.
`page_unavailable` / `empty_selection`	Show the target page in Inkquation or select content with the lasso, then read again.
`busy`	Wait for drawing, pasting or other editor work to finish. Retry an uncertain insertion with the same ID and arguments.
`rate_limited`	Too many calls arrived together. Wait a moment before retrying. If an insertion’s outcome is uncertain, keep the same operation ID and arguments.
`read_limit`	The content is too large to read in one request. Select a smaller area with the lasso and read that selection.
`image_memory_limit`	Visible images or processing fill the image allowance. Wait for processing, scroll away from image-heavy pages, or close unused notes, then retry with the same operation ID and arguments. Read the page again if it changed.
`request_cancelled`	Reading or preparing the edit was cancelled or exceeded its deadline. If needed, choose a smaller area, then read the page again before retrying.
`disconnected`	AI Connection is disabled. Saving an edit already applied continues. Inspect the result in the app, then read the page again after enabling the connection.
`operation_id_reused`	The ID was reused with different arguments. For a retry, use the original tool and arguments.
`isError: true`, `applied: true`, `persisted: false`	The edit or Undo has applied in the running app, but its save is unconfirmed. Inspect the page and retry saving or use Undo in the app. Do not repeat the edit with a new ID.
`undo_conflict`	A later edit or change to Undo history prevents MCP Undo. Review the history with the app’s Undo controls.
`session_limit`	The limit of 128 insertions has been reached. Inspect the results, turn AI Connection off and on in Settings, reconnect the AI app, and read the page again. Do not repeat an earlier edit with a new ID.

MCP Undo is available only while that AI operation is the latest Undo action and its page is unchanged. Operation IDs do not survive disabling AI Connection in Settings or restarting Inkquation. Review earlier operations with the app’s Undo controls.

Connection scope and privacy

The connection communicates with local processes on the same Mac. This website provides documentation; it is not an MCP server that controls notes. Once allowed, the AI app can read available pages in open Inkquation notes. If the AI uses a cloud model, those images may be sent to its provider.

Check which content the AI reads and disable AI Connection when it is no longer needed. Disabling does not remove content already inserted or saved, or data already passed to an external service.

AI connections and privacy

Check available features

This guide reflects the implementation checked on September 9, 2026. Check the connected server’s tools/list separately from app distribution status. If shape or stroke insertion tools are absent, check that your Inkquation build supports them and reconnect the AI app after updating.

Back to Inkquation