Send visual context to an agent

Pinar writes plain Markdown and HTML to the clipboard. The text includes readable annotations plus a fenced pinar-visual-context JSON block. Paste both as one unit; the structured block is the machine-readable source of truth.

If the bundle lists an absolute Screenshot path, the local agent should open that single image; numbered badges are overlays. Warnings such as screenshot_missing, helper_unavailable, or viewer_unavailable describe degraded delivery but do not invalidate the comments and DOM context.

The Chrome extension never types into the agent composer. In Prompt mode, after Command+Enter / Alt+Enter, paste the clipboard yourself into Cursor, Claude, Codex, or Grok. The text begins by saying the pin notes may ask for a change or an explanation, and to treat selector and DOM path as complementary locators, followed by a fenced pinar-visual-context JSON block. If a Viewer URL is included, fetch it only when those details are not enough. In Link mode the agent receives only the session link and needs access to that .md (Pinar Cloud links are private and require an API key or MCP); Off only saves.

Treat captureId and pinId as identity, not labels to rewrite. Visual Context currently encodes schemaVersion 1; parseVisualCapture rejects a missing captureId and any schemaVersion other than 1 or the legacy 0. Follow only what the pins describe. If the person never pasted, ask them to copy again from Pinar instead of reconstructing pins from memory.

• Paste the whole clipboard into the agent; do not retype comments or invent a new captureId.
• Confirm the pasted text still contains a closed pinar-visual-context fence before you start editing code.
• If nothing was pasted, ask for Command+Enter / Alt+Enter in Pinar and follow only the pin notes.

Pinar also exposes its stored sessions through the Model Context Protocol. An MCP client can list projects, collections, batches, sessions, pins, and pin comments, and can create, comment on, rename, move, reorder, and delete them.

The local Pinar service exposes MCP on your own machine without an account, login, or API key. Pinar Cloud requires an API key with the needed permission, and the key’s resource scope bounds what the agent can read, comment on, or change.

For client configuration, including the endpoint, the authentication header, and the protocol details, see the Cloud agent access guide in the Pinar repository.

• An agent-created session stores the page metadata without a screenshot, and an agent pin stores the comment with an optional locator instead of measured geometry.
• MCP does not rehydrate or synchronize the in-browser draft; the extension remains the writer of the active draft, and a later explicit save replaces the stored session under the same id.
• Sharing stays explicit: publish a share from the workspace, or let an agent with the share permission publish or revoke it.

The local Pinar app offers the same Model Context Protocol surface to agents that run on the same computer, and it is open by design: no account, login, or API key is involved. Point your agent's MCP client at the endpoint described in the Agent access to sessions section of the Pinar README.

The Local MCP tools section of the README lists every tool with its arguments and return value. List tools page their results, up to 50 items per page, so an agent walks a large workspace one page at a time. Reorder tools expect the complete list of items and reject a partial one before anything moves.

• Because the connection is local, the agent works only with the captures stored on this computer and never needs Pinar Cloud.
• Most of the cloud tool surface is available locally; the cloud-only extras concern agent keys and publishing shares.

Pinar Cloud lets Pro accounts issue dedicated agent keys. Open Settings → “Agent access” in the workspace to create one: give the key a name, choose a permission — “Read”, “Manage”, “Share”, or “Full” — and an expiry of 7, 30, or 90 days. A “Read” key can be scoped to the entire account or to one project, collection, session, or batch. The other permissions act on the whole account.

The key is shown only once, right after you create it, so copy it before the dialog closes — Pinar keeps only a short prefix and cannot show the key again. Up to 20 active keys can exist at once. Each listed key shows its scope, permission, expiry, and last use, and “Revoke” ends it immediately. A request for a resource outside the key's scope is answered as if the resource did not exist, so a key never reveals what lies beyond its scope. The Cloud agent access guide documents the permission matrix and the full tool surface behind each key.

• Give each agent or automation its own key, so revoking one does not disturb the others.
• Keys work with MCP clients that support custom headers and with the private Markdown links; the “Agent access” panel explains how the key is used.