Connect immut to your AI

This page shows how to let an AI agent protect your files with immut. Pick your tool below. It is written for people and for AI agents. An agent reading this page has all it needs to set itself up.

Agent summary

• Two doors for an agent. Use either, or both. Both are live today.
• Skill (immut-proof, installed from the enroh-ops/immut-agent repo): the scan, classify and protect playbook. npx skills add enroh-ops/immut-agent, then immut setup.
• MCP connector: immut's tools exposed over the Model Context Protocol at https://backend.immut.io/mcp, HTTP transport, 32 tools. Auth with Authorization: Bearer imut_… or x-api-key.
• The connector has no filesystem access. It protects a file you pass it. The skill is the one that reads your disk.
• Get a key: Organization Settings, AI Agents, in app.immut.io. Set IMMUT_API_KEY.
• Building your own integration instead: quickstart and API reference.
• Raw twin of this page: /docs/connect.md.

What are the two ways to connect an agent?

immut is the proof layer for digital files: permanent, independently verifiable, court-ready proof that a file existed at a moment, unchanged. An agent can reach it two ways.

• The skill is the brain. It watches the files that matter, decides what to protect, organises them into folders, protects them, and reports. It runs on hosts that load skills, such as Claude Code and Cursor. The repository is enroh-ops/immut-agent; the skill inside it is named immut-proof, which is the name your agent will use.
• The connector is the tools. It gives immut's actions to any agent that speaks the Model Context Protocol, usually shortened to MCP. Those actions include protecting a file, listing what is protected, and verifying a proof.

They are two doors, not a stack. On Claude Code, install the skill and you are done.

The distinction that matters: only the skill reads your files. The hosted connector runs on immut's servers, with no access to your disk. It protects bytes you hand it. It does not go and find a file. If you want protection to keep happening without you, you want the skill. If you want to say "protect this" in a chat, you want the connector.

Can your AI protect a file at all?

Ask one question before anything else: can your AI open this file from your disk?

• Yes. It can read the real bytes and protect the file correctly.
• No. It can only send bytes you hand it, and it must not guess.

That second case is the one to watch. A chat assistant with a PDF attached does not see the file. It sees the text it extracted. If it sends that text, immut anchors a proof of the text, not of your PDF. You would hold a certificate that verifies and does not match the file on your drive, which is worse than having no proof.

immut refuses this when it can spot it, with FILE_BYTES_NOT_VERIFIED. Do not rely on that. Some formats have no signature to check.

Some examples today. This is not a definitive list: it depends on your setup, not on the product name.

If your AI cannot reach your disk, you can still read and interrogate everything in immut. It is only protecting a new file that needs the real bytes.

Claude Code

Claude Code runs on your machine and can reach your real files. It scans folders and protects them directly.

Scan and protect skill:

npx skills add enroh-ops/immut-agent

Create an agent key in immut (Organization Settings, AI Agents) and set IMMUT_API_KEY.

The skill loads automatically when your task matches it. To drive it, type these to the agent in chat, not into a terminal. Say immut setup to configure it, then immut sweep to find and protect files. They are phrases the skill recognises. This trips people up. immut-cli installs a real binary called immut, so immut verify is a shell command. immut sweep is a sentence. If a phrase does nothing, you are probably in the wrong window.

MCP connector: one command, no bridge needed, because Claude Code passes the header natively.

claude mcp add --transport http immut https://backend.immut.io/mcp \
  --header "Authorization: Bearer imut_your_key"

Claude Desktop

Claude Desktop is good for asking about what you have protected. It cannot protect a new file for you, because it cannot open files from your disk: see the test above. Use Claude Code, the skill, or the web app to protect something.

Scan and protect skill: Desktop chat does not load skills, so use Claude Code for the full experience, or the connector below.

MCP connector: Desktop's add-connector dialog has no header field, so it needs the mcp-remote bridge. Add this to claude_desktop_config.json, then quit and reopen Desktop.

{
  "mcpServers": {
    "immut": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://backend.immut.io/mcp", "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer imut_your_key" }
    }
  }
}

The header is split into an env entry on purpose. Desktop mishandles a space inside a header argument. Authorization:${AUTH} works around it.

Cursor and other IDEs

For Cursor, Windsurf, VS Code, Cline and similar tools. They read your project files, so the skill protects them directly.

Scan and protect skill:

npx skills add enroh-ops/immut-agent

Create an agent key and set IMMUT_API_KEY, then say immut setup and immut sweep to the agent in chat. They are phrases, not shell commands.

MCP connector: save this as .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project. The same shape works in Windsurf, VS Code and Cline.

{
  "mcpServers": {
    "immut": {
      "url": "https://backend.immut.io/mcp",
      "headers": { "Authorization": "Bearer imut_your_key" }
    }
  }
}

ChatGPT, and agents you build yourself

For programmatic agents, or hosts that connect tools over MCP.

MCP connector: any MCP host takes the same pair the Cursor example shows, a URL and an Authorization header. The endpoint is stateless streamable HTTP and accepts POST only.

Plain HTTP: call the API directly. The first command below describes everything immut can do, in a form a machine can read. It needs no key. That is the fastest way to orient an agent you are building.

curl -s https://backend.immut.io/api/v1/docs

curl -s -X POST https://backend.immut.io/api/v1/documents \
  -H "Authorization: Bearer imut_your_key" \
  -F "file=@your-file.pdf" \
  -F "workspace=YOUR_WORKSPACE_ID"

See the API reference and the agent playbook.

What can the connector do?

The hosted connector exposes 32 tools, plus a protect_folder prompt that walks an agent through reviewing a folder and protecting what is worth protecting.

Every tool has its own page under the connector reference, generated from the server, so a tool cannot exist without one. Three machine-readable forms of the same list: mcp-tools.json, the mcp.tools array in GET https://backend.immut.io/api/v1/docs (no key needed), or tools/list on a live session.

Two things the connector genuinely cannot do: create a hash-only proof, and manage webhooks. Both are REST only.

Two limits are worth knowing before you design around it. Both follow from the connector being hosted rather than running on your machine.

• No filesystem access. protect_file and protect_new_version take the file's bytes, base64 encoded. Do not have a model transcribe a large file into base64; for anything substantial, use the skill or POST /documents directly.
• Certificates return metadata, not the PDF. Fetch the document itself from GET /api/v1/certificates/{documentId}.

report_run logs one completed sweep. Call it at the end of every sweep, even one that protected nothing. immut uses these to notice when an agent has stopped running. A sweep you do not report looks the same as an agent that broke.

Each tool enforces the scopes on your key. A tool your key cannot use returns a clean error rather than failing the session, so a narrow key degrades gracefully.

Which should I use?

There are four doors. They differ in who decides what to protect and who can read your files, not in which protocol you prefer.

The skill and the connector are the two ways to give an AI agent immut. The REST API and the CLI are for code.

Two things worth knowing before you choose:

• Only the skill reads your files. The hosted connector has no filesystem access, so it protects a file you pass to it rather than going and finding one. That is why both exist.
• The skill uploads. It classifies locally, then stores the files it selects on immut, after you consent. If bytes must not leave your machine, use the fingerprint path instead (POST /proofs or immut-cli). That is a different mode, and not what the public skill does.

Which API key do I need?

Every call carries an API key. On https://backend.immut.io/api/v1 the only accepted form is Authorization: Bearer imut_live_… (or imut_test_…). The MCP endpoint additionally accepts x-api-key, because some agent hosts only allow that header.

There are two kinds of key. They are not interchangeable.

If you are following the skill's own setup, or anything on the agent playbook, use an agent key. Those pages say "not a personal key" and they mean it. A standard key still works, but the skill's classification metadata is discarded and the upload is recorded as a plain API call. Only an organisation admin or owner can create agent keys.

An agent key records its uploads as agent work, and the distinction is written into the permanent record for each proof. This is a choice you make when you create the key, not something immut detects about the caller.

Agent keys default to the scopes the skill needs: documents:write, documents:read, folders:read, folders:write, certificates:read, workspaces:read. Standard keys require you to choose scopes explicitly, from a wider set that also covers users, billing, webhooks and asset reads. Grant the least you need.

API access is a feature on your subscription rather than a property of any named plan. If a key returns API_ACCESS_DISABLED, the key is valid and the entitlement is not switched on.