AI integration guide

Connect your AI app

1. 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.
2. Open a note in Inkquation. In Settings → AI Connection, allow connections. This is off by default.
3. 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.
4. 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 connection configuration remains valid after normal restarts. Reconnect the AI client if it disconnects. Copy fresh configuration after disabling and re-enabling AI Connection. Keep the configuration private because it contains an access key.

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.

Connect Codex

1. In Inkquation Settings → AI Connection, allow connections, select “Codex / TOML”, and copy the configuration.
2. Open the Codex configuration file in a text editor. The default is ~/.codex/config.toml. In Finder, use Go → Go to Folder to open ~/.codex/.
3. Add the copied [mcp_servers.inkquation] block and save. If that block already exists, update only its settings. Preserve other servers and Codex settings, and do not duplicate the table heading.
4. Keep Inkquation running. Restart Codex’s MCP connection, or save your work and restart Codex. Open a new chat and use the connection-check request below.

To register it through the interface, choose STDIO in Codex’s MCP server settings. Use the copied command value as the command and each args item as an argument in the same order. This connection does not use the website address in a URL field. Screen labels vary by client version.

If you need help, send the following request to Codex on the same Mac. The connection configuration contains a access key: enter it in the local configuration file, rather than pasting it into a chat.

Help me connect Inkquation to Codex over MCP on this Mac. Read the connection instructions at https://inkquation.app/en/ai/ and guide me through copying and saving the configuration. Preserve my existing Codex settings and add or update only the inkquation entry. Do not display the access key or connection configuration in chat or logs. After connecting, list the open notes only; do not edit any notes yet.

• OpenAI: Codex MCP configuration

Connect Claude Desktop

1. In Inkquation’s AI Connection settings, select “Claude Desktop / JSON” and copy the configuration.
2. In Claude Desktop, open Settings → Developer → Edit Config. The default Mac file is ~/Library/Application Support/Claude/claude_desktop_config.json.
3. Add the copied inkquation entry inside the existing mcpServers object. Update an existing entry with that name and preserve other entries. For an empty file, save the entire copied JSON.
4. Keep Inkquation open, fully quit and reopen Claude Desktop, and check the connection in a new chat.

• MCP: local connection instructions for Claude Desktop

Use a local LLM

Running a model on your Mac requires a local model runtime and an AI client that calls Inkquation’s MCP tools. LM Studio combines these roles, so it is the setup example here. These steps follow official documentation; the full workflow with Inkquation has not yet been tested on a Mac.

1. Check LM Studio’s system requirements, then download and load a model that fits your Mac’s memory. Its current Mac version supports Apple Silicon. Choose a model that supports tool calling; reading pages also requires image input.
2. In Inkquation, allow connections under Settings → AI Connection and copy the Claude Desktop / JSON configuration. In LM Studio’s right sidebar, open Program → Install → Edit mcp.json. Labels may vary by version.
3. Add the copied inkquation entry inside the existing mcpServers object and save. Update an existing entry of the same name and preserve other settings. The configuration contains an access key: keep it out of public files and chats.
4. Keep Inkquation open, enable the inkquation tools in the LM Studio chat, and use the connection-check prompt below to retrieve the note list. Once it returns, use the following prompt to check image reading.

Inkquation returns pages as PNG images. A working MCP connection does not establish that the selected model can read images. The AI client must also pass images from tool results to the model. With a text-only model, start by checking note listing only.

List the open Inkquation notes and ask me to choose if there is more than one. Retrieve one available page and describe just two things visible in its image. Do not edit the note. If the image does not reach the model or cannot be read, report that condition instead of guessing its contents.

To process note content on your Mac, select a local model for inference and avoid switching to cloud models or using tools that send content elsewhere. Initial model and runtime downloads, and update checks, are separate network activities.

With Ollama, starting a model alone does not configure the Inkquation connection. Pair it with an AI client that can use Ollama for inference and register local STDIO MCP servers. Add the configuration to that client, then check tool calling and image delivery separately.

• LM Studio: MCP server setup
• LM Studio: system requirements
• LM Studio: offline operation
• Ollama: tool calling

A request to check the connection

Copy the following into your AI chat first. Open a note in Inkquation if none is open.

Use the Inkquation MCP tool inkquation_list_open_notes to tell me the names of the currently open notes and which pages are available to read. This is only a connection check: do not fetch page images or edit anything. If the tool is unavailable, tell me where the connection failed instead of assuming it is connected.

A returned tool result confirms the connection. If the list is empty, open a note and ask again. “Ready · waiting for a client” means Inkquation is ready, not that the AI is connected. Check both the client count and the tool result.

Try a request

Once connected, try the requests below. If several notes are open, specify the note name and page.

• “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.”

Give an AI app a workspace

Use a workspace for code, reference material and generated images you work on with AI. Once you have chosen a storage location, creating, duplicating or importing a note from PDF automatically prepares an empty workspace after the note is saved. Duplicating a note does not copy its workspace files.

1. Create the target note in Inkquation and right-click it in the note list.
2. Use “Open Workspace” to inspect the folder and “Copy Workspace Path” to copy its real path.
3. In an AI app such as Codex, select that folder as the working directory and allow the required file access. You can then ask it to create a reference-material folder there, for example.

To look up the folder through MCP, open the note and call inkquation_get_workspace with the note_id returned by inkquation_list_open_notes. Example arguments:

{
  "note_id": "<note UUID>"
}

This read-only tool does not create folders, change the AI app’s working directory or grant file access. A migration in progress or another workspace problem can return a workspace_unavailable error; check Inkquation’s operation and settings before retrying.

You can also associate an existing project folder with a note. Workspace file contents are excluded from Inkquation’s note backups; manage them with Git or a separate backup.

Workspaces and Library

The paths below illustrate the structure inside your chosen storage location. A note entry under Library/ is a symbolic link to the real folder. Editing a file through the link changes the real file.

Only names that collide within the same parent receive a short ID, such as Experiment--1a2b3c4d. This includes collisions caused by letter case or replacing characters unsuitable for filenames. If short IDs also collide, the suffix grows until the names are distinct.

Renaming or moving notes changes their Library/ paths, so use the copied real folder path as the AI app’s working directory. Creating folders on disk or renaming links does not create or rename notes or folders in the note library.

When the connection does not work

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 inserted by AI become ordinary pen strokes with outlines and no fill. The tool does not provide the fill settings available for rectangles and ellipses drawn in the app. 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.

How an AI should edit a page

1. 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.
2. 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.
3. Choose unused space, then call an insertion tool. Pass the read revision as expected_revision and a fresh UUID as operation_id.
4. 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.

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.

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.

AI connections are off by default. Enabling AI Connection in Settings allows clients using the private access key and the authentic built-in adapter to read open notes and selections and insert images through MCP (Model Context Protocol). The configuration contains an access key; keep it private. Whether configuration survives a restart depends on the app version. Follow the connection and reconfiguration instructions in the AI integration guide.

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

Connection instructions reflect the implementation checked on September 27, 2026; workspace and Library documentation reflects October 1, 2026. This does not mean every distributed version supports these features. Check the connected server’s tools/list. If a required tool or workspace menu item is absent, update to a supporting build and reconnect the AI app. Even when the tool or menu is present, older builds may differ in automatic workspace preparation and Library naming.

• Inkquation availability
• MCP tools specification