MCP connector: use immut as a tool, not an API

immut runs a hosted MCP server. Point your agent host at it and immut becomes a set of tools your model can call. No code, no SDK.

URL: https://backend.immut.io/mcp

This is the fastest way in if your host speaks MCP. If it does not, use the REST API instead. Both do the same work.

How do I connect it?

One command sets it up in Claude Code.

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

Other hosts take a config file. Cursor is one.

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

Create the key in the immut app under Organization Settings, then AI Agents. Per-host setup steps are on the Connect page.

What are the transport rules?

Streamable HTTP, and stateless. POST only. GET and DELETE return 405.

Authenticate with Authorization: Bearer imut_live_.... This endpoint also accepts x-api-key, because some hosts allow no other header. That is true here and nowhere else. The /api/v1 routes require Bearer.

What tools does it expose?

32, each with its own page in the sidebar.

Every page is generated from the server itself, so a tool cannot exist without one. Each lists the arguments, which are required, and the REST endpoint behind it.

Machine-readable forms: the tool contract as JSON, or llms-full.txt for everything in one fetch. Add .md to any tool page for its raw markdown.

Three things to know before you build:

• protect_path is not on the hosted server. It reads the server's own disk, so it is off in production. Use protect_file, which takes the bytes.
• reject_staged deletes permanently. It is the only destructive tool.
• get_certificate returns metadata here, not the PDF. Download that from the app.

Does the connector change what my key can do?

No. It forwards your key to the same v1 API.

Scopes apply exactly as they do over REST. A tool your key lacks scope for returns a clean tool error. It does not end the session. So the connector is a different door, not a wider one.

This matters more than it sounds. A new agent key carries six scopes: documents:write, documents:read, folders:read, folders:write, certificates:read and workspaces:read. Five tools need a scope that is not in that list, so they fail until an admin grants it.

documents:content is the one to think about. Without it a leaked key shows file names. With it, the file contents. That is why it is never a default.

What can the connector not do that the app can?

It adds evidence and reads it back. It does not manage your account or remove anything.

These need a person in the app:

• Delete, rename or move a document, folder or workspace.
• Archive anything, or restore it.
• Build the diligence export as a ZIP.
• Approve or reject a document in the admin queue. That is separate from the agent review queue.
• Add or remove people, or change what they can see.
• Change your plan, your seats or your card.
• Create or revoke an API key.

The pattern is deliberate. An agent adds proof and reports on it. Deleting evidence stays a human decision, made by someone who is signed in.

Two exceptions, because an agent needs them to finish its job. It can reject a file from the review queue, which deletes that staged file for good. It can also revoke a share link belonging to its organisation, including one a person made.

How does immut record a connector upload?

As an API upload. There is no separate connector channel.

A file protected through the connector looks the same in the record as one sent by curl. What changes the record is the kind of key, not the door you came through. An agent key records the upload as agent and keeps the classification you send with it. A personal key records it as api and drops that classification, without an error.

So use an agent key. A personal key still works, and you will not be told what you lost.

Can it read files off my computer?

No. The hosted server has no filesystem access.

It protects bytes you pass it. If you want something that reads your disk and decides what matters, that is the agent skill, which runs on your own machine. The two are complements. Many teams run both.

This matters more if your AI cannot read your disk either. Ask whether your assistant can open the file itself. A chat window with a PDF attached cannot: it has the text it extracted, not the file. Sending that text would anchor a proof of the text, and the certificate would not match the customer's file. immut refuses when it can spot it, returning FILE_BYTES_NOT_VERIFIED, but some formats have no signature to check. If you cannot open the file, say so and stop. Do not reconstruct it.

Local file reading exists in the code for people self-hosting the server beside themselves. It is ignored in production, whatever the environment says. A public deployment must never read arbitrary host paths.

Which should I use, the connector or the skill?

Pick by what you need it to do.

What happens when a tool call fails?

You get a tool error with the same codes the REST API uses.

Read the code, not the message. The list, and which errors are worth retrying, is on the Errors page.