Browse the user guide

How agent access works

How Claude, Codex and other AI agents use the Shotomatic app over a local MCP server, what you control, and where to start.

Updated November 16, 2026

View Markdown
On this page

AI agents such as Claude Code, the Claude app, and Codex can use Shotomatic on your Mac or Windows PC. They work through the same features you use: Auto Capture, Action Capture, Website Capture, Capture History, Documents, and export. You describe the result, and the agent picks the steps.

How a request reaches Shotomatic

Agents connect over MCP, the Model Context Protocol. Shotomatic's MCP server is local:

  1. Your agent starts a small bridge on your computer. Connect in Settings registers a bridge that ships with Shotomatic; other clients start the shotomatic package with npx -y shotomatic mcp.
  2. The bridge passes the agent's requests to the Shotomatic app through a private local connection: a socket on a Mac, a named pipe on Windows. If Shotomatic is not running, the bridge opens it in the background.
  3. Shotomatic runs the request, such as a capture or an export, and returns the result to the agent.

There is no hosted Shotomatic server, no account to sign in to, and no API key. Shotomatic opens no network port, and only your own user account can connect. Images the agent looks at become part of its conversation, which the agent's provider handles under its own terms.

What you control

  • Access switch. Let AI agents use Shotomatic in Settings > AI agents is off by default. Turning it off disconnects every agent.
  • One approval per agent. An agent you did not connect from Settings must be allowed once on an approval card.
  • Confirmations. Shotomatic asks you before an agent deletes anything, lowers the Capture History limit so that sessions are removed, or schedules a Workflow.
  • Stop at any time. A capture an agent starts shows the normal capture toolbar, and Disconnect in the status row closes every agent connection.

Agents use your plan and your macOS permissions. See Limits and safety.

Choose how to connect

Your agentHow to connect
Claude Code, the Claude app, or CodexConnect in Settings, no Node needed
Cursor, VS Code, Gemini CLI, Zed, and othersA command or settings entry for your client

Where to go next

How agent access works | User Guide | Shotomatic